puma-release 0.1.0

data/lib/puma_release/release_range.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PumaRelease
+  class ReleaseRange
+    attr_reader :context, :last_tag
+
+    def initialize(context, last_tag)
+      @context = context
+      @last_tag = last_tag
+    end
+
+    def items
+      @items ||= begin
+        seen_prs = {}
+        commits.filter_map do |commit|
+          pr = github.commit_pulls(context.metadata_repo, commit.fetch(:sha)).first
+          if pr
+            next if seen_prs[pr.fetch("number")]
+
+            seen_prs[pr.fetch("number")] = true
+            pull_request_item(pr, commit.fetch(:sha))
+          else
+            commit.merge(type: "commit")
+          end
+        end
+      end
+    end
+
+    def to_prompt_context
+      lines = ["Repository: #{context.metadata_repo}", "Release range: #{last_tag}..HEAD", "", "Changes:"]
+      items.each do |item|
+        if item.fetch(:type) == "pr"
+          labels = item.fetch(:labels)
+          lines << "- PR ##{item.fetch(:number)} #{item.fetch(:title)}"
+          lines << "  Labels: #{labels.empty? ? "none" : labels.join(", ")}"
+          lines << "  PR URL: #{item.fetch(:url)}"
+          lines << "  Merge commit: #{item.fetch(:commit_url)}"
+        else
+          lines << "- Commit #{item.fetch(:sha)[0, 12]} #{item.fetch(:subject)}"
+          lines << "  Commit URL: #{item.fetch(:commit_url)}"
+        end
+      end
+      lines.join("\n")
+    end
+
+    private
+
+    def commits
+      shell.output("git", "log", "--reverse", "--format=%H%x09%s", "#{last_tag}..HEAD").lines(chomp: true).map do |line|
+        sha, subject = line.split("\t", 2)
+        {sha:, subject:, commit_url: "https://github.com/#{context.metadata_repo}/commit/#{sha}"}
+      end
+    end
+
+    def pull_request_item(pr, sha)
+      {
+        type: "pr",
+        number: pr.fetch("number"),
+        title: pr.fetch("title"),
+        url: pr.fetch("html_url"),
+        commit_url: "https://github.com/#{context.metadata_repo}/commit/#{sha}",
+        labels: Array(pr["labels"]).map { |label| label.fetch("name") }
+      }
+    end
+
+    def shell = context.shell
+    def github = @github ||= GitHubClient.new(context)
+  end
+end

data/lib/puma_release/repo_files.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "date"
+
+module PumaRelease
+  class RepoFiles
+    attr_reader :context
+
+    def initialize(context)
+      @context = context
+    end
+
+    def current_version
+      content[/PUMA_VERSION = VERSION = "([^"]+)"/, 1] || raise(Error, "Could not read current version")
+    end
+
+    def current_code_name
+      content[/CODE_NAME = "([^"]+)"/, 1] || raise(Error, "Could not read current code name")
+    end
+
+    def release_name(version)
+      return "v#{version}" unless codename_applicable?(version)
+
+      "v#{version} - #{current_code_name}"
+    end
+
+    def update_security!(new_version)
+      major = new_version.split(".").first.to_i
+      new_majors = [major, major - 1]
+      i = -1
+      updated = context.security_file.read.gsub(/Latest release in \d+\.x/) do
+        i += 1
+        i < new_majors.size ? "Latest release in #{new_majors[i]}.x" : $&
+      end
+      context.security_file.write(updated)
+    end
+
+    def update_version!(new_version, bump_type, codename: nil)
+      updated = content.sub(/PUMA_VERSION = VERSION = ".*"/, "PUMA_VERSION = VERSION = \"#{new_version}\"")
+      unless bump_type == "patch"
+        placeholder = codename || "INSERT CODENAME HERE"
+        updated = updated.sub(/CODE_NAME = ".*"/, "CODE_NAME = \"#{placeholder}\"")
+      end
+      context.version_file.write(updated)
+    end
+
+    def extract_history_section(version)
+      lines = context.history_file.readlines(chomp: true)
+      start = lines.index { |line| line.match?(/^## #{Regexp.escape(version)} /) }
+      return nil unless start
+
+      lines[(start + 1)..].take_while { |line| !line.start_with?("## ") }.join("\n").strip
+    end
+
+    def prepend_history_section!(version, changelog, refs)
+      header = "## #{version} / #{Date.today.strftime("%Y-%m-%d")}"
+      body = [header, changelog.strip, context.history_file.read].join("\n\n")
+      context.history_file.write(body)
+      insert_link_refs!(refs)
+    end
+
+    def insert_link_refs!(refs)
+      return if refs.empty?
+
+      lines = context.history_file.readlines(chomp: true)
+      index = lines.index { |line| line.match?(/^\[#\d+\]:/) }
+      updated = if index
+        [*lines[0...index], *refs.lines(chomp: true), *lines[index..]].join("\n")
+      else
+        [context.history_file.read.rstrip, refs].join("\n")
+      end
+      context.history_file.write("#{updated}\n")
+    end
+
+    private
+
+    def codename_applicable?(version)
+      version.split(".").last == "0"
+    end
+
+    def content
+      context.version_file.read
+    end
+  end
+end

data/lib/puma_release/shell.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "shellwords"
+
+module PumaRelease
+  class Shell
+    Result = Data.define(:stdout, :stderr, :success?, :exitstatus)
+
+    attr_reader :env, :cwd
+
+    def initialize(env: ENV, cwd: Dir.pwd)
+      @env = env.to_h
+      @cwd = cwd
+    end
+
+    def available?(command)
+      return File.file?(command) && File.executable?(command) if command.include?(File::SEPARATOR)
+
+      env.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |path|
+        candidate = File.join(path, command)
+        File.file?(candidate) && File.executable?(candidate)
+      end
+    end
+
+    def run(*command, stdin_data: nil, env_overrides: {}, allow_failure: false)
+      stdout, stderr, status = Open3.capture3(env.merge(env_overrides), *command, stdin_data:, chdir: cwd)
+      result = Result.new(stdout:, stderr:, success?: status.success?, exitstatus: status.exitstatus)
+      return result if result.success? || allow_failure
+
+      details = result.stderr.strip
+      details = result.stdout.strip if details.empty?
+      raise Error, [command.join(" "), details].reject(&:empty?).join(": ")
+    end
+
+    def output(*command, **options)
+      run(*command, **options).stdout
+    end
+
+    def stream_output(*command, stdin_data: nil, env_overrides: {})
+      stdout_buffer = +""
+      stderr_buffer = +""
+
+      Open3.popen3(env.merge(env_overrides), *command, chdir: cwd) do |stdin, stdout, stderr, wait_thr|
+        stdin.write(stdin_data) if stdin_data
+        stdin.close
+
+        stdout_thread = Thread.new do
+          stream_chunks(stdout) do |chunk|
+            $stdout.print(chunk)
+            $stdout.flush
+            stdout_buffer << chunk
+            yield chunk if block_given?
+          end
+        end
+
+        stderr_thread = Thread.new do
+          stream_chunks(stderr) { |chunk| stderr_buffer << chunk }
+        end
+
+        stdout_thread.join
+        stderr_thread.join
+        status = wait_thr.value
+        return stdout_buffer if status.success?
+
+        details = stderr_buffer.strip
+        details = stdout_buffer.strip if details.empty?
+        raise Error, [command.join(" "), details].reject(&:empty?).join(": ")
+      end
+    end
+
+    def stream_json_events(*command, stdin_data: nil, env_overrides: {})
+      Open3.popen3(env.merge(env_overrides), *command, chdir: cwd) do |stdin, stdout, stderr, wait_thr|
+        stdin.write(stdin_data) if stdin_data
+        stdin.close
+        stdout.each_line do |line|
+          next if line.strip.empty?
+          begin
+            yield JSON.parse(line)
+          rescue JSON::ParserError
+          end
+        end
+        status = wait_thr.value
+        raise Error, command.join(" ") unless status.success?
+      end
+    end
+
+    def optional_output(*command)
+      run(*command, allow_failure: true).stdout.strip
+    end
+
+    def split(command)
+      Shellwords.split(command)
+    end
+
+    private
+
+    def stream_chunks(io)
+      loop do
+        chunk = io.readpartial(1024)
+        yield chunk
+      end
+    rescue EOFError
+    end
+  end
+end

data/lib/puma_release/stage_detector.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module PumaRelease
+  class StageDetector
+    attr_reader :context, :git_repo, :repo_files, :github
+
+    def initialize(context, git_repo: GitRepo.new(context), repo_files: RepoFiles.new(context), github: GitHubClient.new(context))
+      @context = context
+      @git_repo = git_repo
+      @repo_files = repo_files
+      @github = github
+    end
+
+    def next_step
+      return :wait_for_merge if waiting_on_release_pr?
+      return :build if release_version_ahead_of_tag?
+      return :github if github_release_pending?
+      return :github if github_release_missing_for_current_tag?
+      return :complete if no_new_commits_since_last_release?
+
+      :prepare
+    end
+
+    private
+
+    def waiting_on_release_pr?
+      return true if git_repo.current_branch.start_with?("release-v")
+
+      !github.open_release_pr.nil?
+    end
+
+    def release_version_ahead_of_tag?
+      repo_files.current_version != git_repo.last_tag.delete_prefix("v")
+    end
+
+    def github_release_pending?
+      release = current_release
+      return false unless release
+
+      release.fetch("isDraft", false) || missing_assets?(release)
+    end
+
+    def github_release_missing_for_current_tag?
+      current_release.nil? && no_new_commits_since_last_release?
+    end
+
+    def no_new_commits_since_last_release?
+      git_repo.commits_since(git_repo.last_tag).zero?
+    end
+
+    def current_release
+      return @current_release if defined?(@current_release)
+
+      @current_release = github.release(git_repo.release_tag(repo_files.current_version))
+    end
+
+    def missing_assets?(release)
+      assets = Array(release["assets"]).map { |asset| asset["name"] }
+      (expected_assets - assets).any?
+    end
+
+    def expected_assets
+      ["puma-#{repo_files.current_version}.gem", "puma-#{repo_files.current_version}-java.gem"]
+    end
+  end
+end

data/lib/puma_release/ui.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PumaRelease
+  class UI
+    COLORS = {
+      info: "\e[0;32m",
+      warn: "\e[1;33m",
+      error: "\e[0;31m",
+      debug: "\e[0;36m",
+      reset: "\e[0m"
+    }.freeze
+
+    def info(message) = $stdout.puts(colorize(:info, message))
+    def warn(message) = $stdout.puts(colorize(:warn, message))
+    def error(message) = warn(colorize(:error, message))
+    def debug(message) = warn(colorize(:debug, "[DEBUG] #{message}"))
+
+    def confirm(message, default: true)
+      return default unless $stdin.tty?
+
+      suffix = default ? "[Y/n]" : "[y/N]"
+      $stdout.print("#{message} #{suffix} ")
+      answer = $stdin.gets.to_s.strip.downcase
+      return default if answer.empty?
+
+      answer.start_with?("y")
+    end
+
+    private
+
+    def colorize(kind, message)
+      color = COLORS.fetch(kind)
+      "#{color}==>#{COLORS.fetch(:reset)} #{message}"
+    end
+  end
+end

data/lib/puma_release/upgrade_guide_writer.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module PumaRelease
+  class UpgradeGuideWriter
+    SYSTEM_PROMPT = <<~PROMPT.strip
+      You are writing the upgrade guide for a new major version of Puma, a Ruby web server gem.
+
+      Follow this structure exactly:
+
+      # Welcome to Puma X.X: Codename.
+
+      (2-3 sentences describing what this release brings and why users should be excited.)
+
+      Here's what you should do:
+
+      1. Review the Upgrade section below to look for breaking changes that could affect you.
+      2. Upgrade to version X.0 in your Gemfile and deploy.
+      3. Open up a new bug issue if you find any problems.
+      4. Join us in building Puma! We welcome first-timers. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+      For a complete list of changes, see [History.md](./History.md).
+
+      ## What's New
+
+      (Describe the major user-facing features and improvements in this release. Group related
+      items under sub-headers if there are multiple themes. For each significant feature,
+      explain what it is, why it matters to the user, and how to use or configure it — include
+      a code example if applicable. Link to relevant PRs and issues using Markdown links to
+      https://github.com/puma/puma/pull/NUMBER or /issues/NUMBER. Omit pure internal
+      refactors, CI changes, and test-only changes.)
+
+      ## Upgrade
+
+      Check the following list to see if you're depending on any of these behaviors:
+
+      (A numbered list. Each item must be specific and actionable: name the exact DSL method,
+      CLI flag, environment variable, Ruby constant, or behavior that changed, and explain
+      exactly what the user needs to do. Cover every breaking change provided. Use inline code
+      formatting for config keys, env vars, CLI flags, Ruby class/method names, etc.)
+
+      Then, update your Gemfile:
+
+      `gem 'puma', '< X+1'`
+
+      Tone and style rules:
+      - Friendly and direct, matching the voice of the existing Puma upgrade guides.
+      - Do not include an image line.
+      - Do not invent breaking changes beyond what is provided and supported by the commit list.
+      - Do not include a "then update your Gemfile" line at the end of the What's New section.
+      - The Upgrade section must cover every breaking change in the provided list.
+    PROMPT
+
+    attr_reader :context, :release_range, :new_version, :breaking_changes, :codename
+
+    def initialize(context, release_range, new_version:, breaking_changes:, codename:)
+      @context = context
+      @release_range = release_range
+      @new_version = new_version
+      @breaking_changes = breaking_changes
+      @codename = codename
+    end
+
+    def call
+      context.ui.info("Asking #{context.agent_cmd} to write upgrade guide for #{new_version}...")
+      content = agent.ask_for_text(prompt, system_prompt: SYSTEM_PROMPT)
+      path = upgrade_guide_path
+      File.write(path, content.strip + "\n")
+      context.ui.info("Wrote upgrade guide: #{path}")
+      path
+    end
+
+    private
+
+    def upgrade_guide_path
+      major_minor = new_version.split(".").first(2).join(".")
+      File.join(context.repo_dir, "docs", "#{major_minor}-Upgrade.md")
+    end
+
+    def prompt
+      version_label = codename ? "#{new_version} (\"#{codename}\")" : new_version
+      next_major = new_version.split(".").first.to_i + 1
+
+      breaking_section = if breaking_changes.any?
+        "The following breaking changes have been identified for this release:\n\n" +
+          breaking_changes.map { |c| "- #{c}" }.join("\n")
+      else
+        "No specific breaking changes were pre-identified by the version recommender, " \
+          "but this is a major version bump. Review the commits carefully for anything " \
+          "that could require user action when upgrading."
+      end
+
+      <<~PROMPT
+        Write the upgrade guide for Puma #{version_label}.
+
+        The next major version after this will be #{next_major}, so the Gemfile constraint
+        at the end of the Upgrade section should read: `gem 'puma', '< #{next_major}'`
+
+        #{breaking_section}
+
+        #{release_range.to_prompt_context}
+      PROMPT
+    end
+
+    def agent = @agent ||= AgentClient.new(context)
+  end
+end

data/lib/puma_release/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PumaRelease
+  VERSION = "0.1.0"
+end

data/lib/puma_release/version_recommender.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module PumaRelease
+  class VersionRecommender
+    SYSTEM_PROMPT = <<~PROMPT.strip
+      You are deciding the semantic version bump for the next Puma release.
+
+      The 'breaking change' label on a PR means a major bump is DEFINITELY required. However,
+      the absence of that label does not mean a major bump isn't warranted — it just means no
+      one explicitly flagged it. You must independently assess every PR and commit for potential
+      breaking changes regardless of labels.
+
+      A breaking change is anything that could require users to update their code, configuration,
+      or deployment when upgrading. Be expansive: consider changes to public APIs, behavior
+      changes in existing options or hooks, changes to default values, removed or renamed
+      configuration, changes to supported Ruby or platform versions, changes to the Rack/HTTP
+      interface, changes to how signals are handled, changes to logging or error output format,
+      changes to gem dependencies, and any other change a user might feel when upgrading.
+
+      ## Puma's public API
+
+      The following are public API surfaces. Changes that alter their behavior, shape, or
+      availability are potentially breaking and must be flagged.
+
+      **HTTP→Rack env mapping.** For the same HTTP input bytes, Puma must produce the same
+      Rack env. This covers REQUEST_METHOD, PATH_INFO, QUERY_STRING, CONTENT_TYPE,
+      CONTENT_LENGTH, HTTP_* headers, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL, REMOTE_ADDR,
+      GATEWAY_INTERFACE, etc.
+
+      **Puma-specific Rack env extensions.** puma.socket, puma.peercert, and puma.config.
+      Also the standard Rack extensions Puma populates: rack.hijack?, rack.hijack,
+      rack.after_reply, rack.response_finished, rack.early_hints.
+
+      **Configuration DSL.** All methods available in puma.rb / Puma.configure blocks,
+      including lifecycle hooks: before_fork, after_booted, before_worker_boot,
+      before_worker_shutdown, after_worker_fork, after_worker_shutdown, before_restart,
+      before_thread_start, before_thread_exit, out_of_band, lowlevel_error_handler. Changes
+      to hook signatures or timing are breaking. Changes to default values of any option
+      (thread counts, timeouts, etc.) are also breaking.
+
+      **Deprecated hook aliases.** The old-style hooks (on_booted, on_restart, on_stopped,
+      on_worker_boot, on_worker_fork, on_worker_shutdown, on_refork, on_thread_start,
+      on_thread_exit) are deprecated but still supported. Removing them counts as a breaking
+      change even though they are deprecated.
+
+      **CLI interface.** All flags to the puma binary. Adding flags is a new feature (minor);
+      removing or changing the behavior of existing flags is breaking.
+
+      **Plugin interface.** The contract for writing a plugin: Plugin.create, the config(dsl)
+      hook receiving the DSL object, and the start(launcher) hook. Changes to what DSL and
+      Launcher expose to plugins are breaking for plugin authors.
+
+      **Control server REST API.** The HTTP interface exposed via activate_control_app:
+      endpoints /stop, /halt, /restart, /phased-restart, /refork, /stats, /gc, /gc-stats,
+      /thread-backtraces, /status, and their response formats.
+
+      **pumactl CLI.** The pumactl command and its available subcommands. Operators use this
+      in deploy scripts and process supervisors.
+
+      **State file format.** The fields written to the state file: pid, control_url,
+      control_auth_token, running_from. Tools that restart or monitor Puma read this.
+
+      **Puma.stats / Puma.stats_hash output shape.** The structure of the stats JSON.
+      Monitoring integrations parse specific fields; removing or renaming them is breaking.
+
+      **Signal behavior.** How Puma responds to OS signals (TERM, INT, USR1, USR2, HUP) in
+      both single and cluster mode.
+
+      **Supported Ruby and platform versions.** Dropping support for a Ruby version or
+      platform is breaking for users on that version.
+
+      ## Not part of Puma's public API
+
+      The following are implementation details. Changes here are not breaking on their own.
+
+      - Puma::Server (the Ruby class and its API)
+      - Parser classes (Puma::HttpParser, etc.) — the Ruby class API is internal; only the
+        HTTP parsing behavior visible in the Rack env is public
+      - Puma::Launcher, Puma::Runner, Puma::Worker, Puma::ThreadPool, Puma::Reactor,
+        Puma::Client
+      - Puma::Configuration as a Ruby class (the DSL behavior is public; the class is not)
+      - Internal pipe/signal constants (PIPE_WAKEUP, PIPE_BOOT, etc.)
+      - Log message text and format (unless explicitly documented as stable)
+      - Internal gem require paths
+
+      Recommend major if the 'breaking change' label is present on any PR, OR if your analysis
+      identifies any likely breaking changes. Otherwise recommend minor if any PR or commit
+      looks like a feature, new option, new hook, new capability, or other user-facing
+      enhancement. Otherwise recommend patch. When deciding between patch and minor, prefer minor.
+
+      Return exactly one markdown paragraph for reasoning_markdown, and include direct markdown
+      links to the commit URLs that drove the recommendation.
+
+      For breaking_changes, list every potential breaking change you can identify — even ones
+      that seem minor or unlikely to affect most users. Each entry should name the change and
+      briefly explain why it could break something. If you find none, return an empty array.
+    PROMPT
+
+    SCHEMA = {
+      type: "object",
+      required: %w[bump_type reasoning_markdown breaking_changes],
+      additionalProperties: false,
+      properties: {
+        bump_type: {type: "string", enum: %w[patch minor major]},
+        reasoning_markdown: {type: "string", minLength: 1},
+        breaking_changes: {
+          type: "array",
+          items: {type: "string", minLength: 1}
+        }
+      }
+    }.freeze
+
+    attr_reader :context, :release_range
+
+    def initialize(context, release_range)
+      @context = context
+      @release_range = release_range
+    end
+
+    def call
+      context.ui.info("Asking #{context.agent_cmd} to recommend the version bump...")
+      recommendation = agent.ask_for_json(prompt, system_prompt: SYSTEM_PROMPT, schema: SCHEMA)
+      bump_type = recommendation.fetch("bump_type")
+      reasoning = recommendation.fetch("reasoning_markdown").strip
+      raise Error, "#{context.agent_cmd} returned an invalid bump type" unless %w[patch minor major].include?(bump_type)
+      raise Error, "#{context.agent_cmd} returned empty bump reasoning" if reasoning.empty?
+      raise Error, "#{context.agent_cmd} must include commit links in its reasoning" unless reasoning.include?("https://github.com/#{context.metadata_repo}/commit/")
+      raise Error, "#{context.agent_cmd} must return bump reasoning as a single paragraph" if reasoning.include?("\n\n")
+
+      {
+        "bump_type" => bump_type,
+        "reasoning_markdown" => reasoning,
+        "breaking_changes" => recommendation.fetch("breaking_changes"),
+        "model_name" => agent.last_model_name || context.comment_author_model_name
+      }
+    end
+
+    private
+
+    def prompt
+      <<~PROMPT
+        Determine the semantic version bump for the next Puma release.
+        Return JSON that matches the provided schema.
+
+        #{release_range.to_prompt_context}
+      PROMPT
+    end
+
+    def agent = @agent ||= AgentClient.new(context)
+  end
+end

data/lib/puma_release.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "puma_release/version"
+require_relative "puma_release/error"
+require_relative "puma_release/events"
+require_relative "puma_release/ui"
+require_relative "puma_release/shell"
+require_relative "puma_release/options"
+require_relative "puma_release/context"
+require_relative "puma_release/repo_files"
+require_relative "puma_release/git_repo"
+require_relative "puma_release/github_client"
+require_relative "puma_release/contributor_resolver"
+require_relative "puma_release/release_range"
+require_relative "puma_release/agent_client"
+require_relative "puma_release/ci_checker"
+require_relative "puma_release/version_recommender"
+require_relative "puma_release/changelog_validator"
+require_relative "puma_release/changelog_generator"
+require_relative "puma_release/link_reference_builder"
+require_relative "puma_release/upgrade_guide_writer"
+require_relative "puma_release/build_support"
+require_relative "puma_release/stage_detector"
+require_relative "puma_release/commands/prepare"
+require_relative "puma_release/commands/build"
+require_relative "puma_release/commands/github"
+require_relative "puma_release/commands/run"
+require_relative "puma_release/cli"