ratatui_ruby-devtools 0.1.0

data/exe/announce

@@ -0,0 +1,1120 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+####
+# ======================================================================
+# announce_tui - TUI for release announcements (experimental)
+# ======================================================================
+#
+# SYNOPSIS
+#     bin/announce_tui [OPTIONS] [VERSION]
+#
+# DESCRIPTION
+#     A TUI for managing release announcements. Displays email preview,
+#     commit preview, and a release checklist with action controls.
+#
+# OPTIONS
+#     -w, --wiki-dir PATH    Path to wiki repo (default: ../ratatui_ruby-wiki)
+#     -n, --builds N         Number of builds to show (default: 4)
+#     -h, --help             Show this help message
+#
+# ======================================================================
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ratatui_ruby"
+require "uri"
+require "optparse"
+require "fileutils"
+require "tmpdir"
+
+# A path flag value with display methods.
+#
+# CLI flags need both full and abbreviated display. Paths are long. Home
+# directory abbreviation improves readability.
+#
+# [value] The path string.
+PathFlag = Data.define(:value) do
+  # Returns the full path value.
+  def to_s = value
+
+  # Returns an abbreviated path using ~ for home directory.
+  def to_short
+    home = Dir.home
+    value.start_with?(home) ? value.sub(home, "~") : value
+  end
+end
+
+# A boolean flag value with display methods.
+#
+# CLI flags need string representation for display. This wraps a boolean
+# with <tt>to_s</tt> and <tt>to_short</tt> methods.
+#
+# [value] The boolean value.
+BoolFlag = Data.define(:value) do
+  # Returns "true" or "false".
+  def to_s = value.to_s
+
+  # Returns "yes" or "no".
+  def to_short = value ? "yes" : "no"
+end
+
+# An integer flag value with display methods.
+#
+# CLI flags need string representation for display. This wraps an integer
+# with <tt>to_s</tt> and <tt>to_short</tt> methods.
+#
+# [value] The integer value.
+IntFlag = Data.define(:value) do
+  # Returns the integer as a string.
+  def to_s = value.to_s
+
+  # Returns the integer as a string.
+  def to_short = value.to_s
+end
+
+# Global CLI flags singleton.
+#
+# CLI options need to be accessible throughout the application. Passing them
+# through every method call is verbose. A module-level singleton provides
+# clean access.
+module CLIFlags
+  class << self
+    # Whether to perform a dry run (no side effects).
+    attr_accessor :dry_run
+
+    # Path to the wiki repository.
+    attr_accessor :wiki_dir
+
+    # Number of builds to display.
+    attr_accessor :builds
+
+    # Version to announce.
+    attr_accessor :version
+  end
+
+  self.dry_run = BoolFlag.new(false)
+  self.builds = IntFlag.new(4)
+end
+
+# Reads and parses release announcement files.
+#
+# Release announcements live in the wiki repo as markdown files. They contain
+# a Subject line and body for mailing list posts. Parsing them manually each
+# time is tedious.
+#
+# This class reads announcement files, extracts subject and body, and generates
+# commit messages. It checks both stable and devel announcement directories.
+#
+# Use it to preview and send release emails.
+class Announcement
+  # The email subject line.
+  attr_reader :subject
+
+  # The email body content.
+  attr_reader :body
+
+  # The file path to the announcement.
+  attr_reader :path
+
+  # Creates an Announcement for a version.
+  #
+  # [wiki_dir] Path to the wiki repository.
+  # [version] The version string (e.g., "v1.2.3").
+  def initialize(wiki_dir, version)
+    # Prefer announcements/ (major/minor) over devel-announcements/ (patches)
+    stable_path = File.join(wiki_dir, "announcements", "#{version}.md")
+    devel_path = File.join(wiki_dir, "devel-announcements", "#{version}.md")
+    @path = File.exist?(stable_path) ? stable_path : devel_path
+    @subject = nil
+    @body = nil
+    parse
+  end
+
+  # Checks whether the announcement file exists on disk.
+  #
+  # The UI previews announcement content. Missing files produce errors or empty
+  # previews. Check this before accessing subject or body to avoid confusion.
+  def exists?
+    File.exist?(@path)
+  end
+
+  # Generates a conventional commit message for this announcement.
+  #
+  # Announcements get committed to the wiki. Consistent commit messages aid
+  # changelog generation and git log readability. This generates the message
+  # following project conventions.
+  def commit_message
+    <<~MSG
+      docs: add #{File.basename(@path, '.md')} release announcement
+
+      Generated with [Antigravity](https://antigravity.google)
+
+      Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>
+    MSG
+  end
+
+  private def parse
+    unless exists?
+      @subject = "(Announcement file not found)"
+      @body = "Expected file: #{@path}"
+      return
+    end
+
+    content = File.read(@path)
+    lines = content.lines
+
+    subject_line = lines.find { |l| l.start_with?("Subject: ") }
+    if subject_line
+      @subject = subject_line.sub(/^Subject: /, "").strip
+      subject_index = lines.index(subject_line)
+      body_lines = lines[(subject_index + 1)..]
+        .reject { |l| l.match?(/^<!--/) || l.match?(/-->/) }
+      @body = body_lines.join.strip
+    else
+      @subject = "(No subject found)"
+      @body = content
+    end
+  end
+end
+
+# Queries git repository state for release verification.
+#
+# Releases require the correct git tag to exist and be pushed. Checking these
+# conditions manually is error-prone. Network latency makes synchronous checks
+# slow.
+#
+# This class queries local and remote tags. It spawns background processes for
+# network operations. It caches results for responsive UI.
+#
+# Use it to verify release preconditions.
+class GitRepo
+  # Temp file for background check results.
+  CACHE_FILE = File.join(Dir.tmpdir, "ratatui_git_tag_pushed.txt")
+
+  # The latest git tag in the repository.
+  attr_reader :latest_tag
+
+  # The expected version tag (e.g., "v1.2.3").
+  attr_reader :expected_version
+
+  # Whether the tag has been pushed to origin.
+  attr_reader :tag_pushed
+
+  # Creates a new GitRepo and starts background checks.
+  def initialize
+    @expected_version = "v#{RatatuiRuby::VERSION}"
+    @latest_tag = `git describe --tags --abbrev=0 2>/dev/null`.strip
+    @latest_tag = nil if @latest_tag.empty?
+    @tag_pushed = nil
+    @loading = true
+    @check_pid = nil
+
+    # Spawn background process BEFORE TUI enters raw mode
+    start_background_check if tag_matches?
+  end
+
+  # Compares the latest git tag against the expected version.
+  #
+  # Releases require the correct tag. A mismatch indicates the tag wasn't
+  # created or the wrong branch is checked out. Check this before proceeding
+  # with release steps.
+  def tag_matches?
+    @latest_tag == @expected_version
+  end
+
+  # Indicates whether background network checks are in progress.
+  #
+  # The TUI shows loading indicators while fetching remote data. Displaying
+  # stale data confuses users. Poll this to update the loading UI and detect
+  # when fresh data arrives.
+  def loading?
+    return false unless @loading
+
+    # Poll for background process completion
+    if @check_pid
+      _pid, status = Process.waitpid2(@check_pid, Process::WNOHANG)
+      if status
+        # Process completed, read result
+        @tag_pushed = File.exist?(CACHE_FILE) && File.read(CACHE_FILE).strip == "true"
+        @loading = false
+        @check_pid = nil
+      end
+    end
+    @loading
+  end
+
+  # Fetches tag information from git synchronously.
+  #
+  # The user triggers manual refresh. Synchronous fetch blocks but guarantees
+  # fresh data. Use this for explicit refresh actions, not TUI polling loops.
+  def refresh
+    @loading = true
+    @latest_tag = `git describe --tags --abbrev=0 2>/dev/null`.strip
+    @latest_tag = nil if @latest_tag.empty?
+    @tag_pushed = check_tag_pushed_sync
+    @loading = false
+  end
+
+  # Refreshes tag information in the background.
+  #
+  # The TUI polls for fresh data while rendering. Synchronous network calls
+  # freeze the interface. This method spawns a background process so the UI
+  # stays responsive.
+  def refresh_async
+    @loading = true
+    start_background_check if tag_matches?
+  end
+
+  private def start_background_check
+    # Spawn process that runs git and writes result to temp file
+    @check_pid = Process.spawn(
+      "git ls-remote --tags origin 2>/dev/null | grep -q '#{@expected_version}' && echo true > #{CACHE_FILE} || echo false > #{CACHE_FILE}"
+    )
+  end
+
+  private def check_tag_pushed_sync
+    return false unless tag_matches?
+    remote_tags = `git ls-remote --tags origin 2>/dev/null`.strip
+    remote_tags.include?(@expected_version)
+  end
+end
+
+# Queries SourceHut build status.
+#
+# Releases should wait for CI to pass. Checking SourceHut manually is tedious.
+# Network latency makes synchronous checks slow.
+#
+# This class queries build status via the hut CLI. It refreshes in background
+# threads. It reports aggregate pass/fail/running status.
+#
+# Use it to verify CI status before releasing.
+class SourceHut
+  # Array of build hashes with :id and :status keys.
+  attr_reader :builds
+
+  # Creates a new SourceHut query.
+  #
+  # [max_builds] Maximum number of builds to track.
+  def initialize(max_builds: 4)
+    @max_builds = max_builds
+    @builds = []
+    @loading = true
+    refresh_async
+  end
+
+  # Indicates whether build data is being fetched.
+  #
+  # The TUI shows loading indicators while fetching. Displaying stale build
+  # status misleads users. Poll this to show spinners and detect when fresh
+  # data arrives.
+  def loading?
+    @loading
+  end
+
+  # Fetches build information from SourceHut synchronously.
+  #
+  # The user triggers manual refresh. Synchronous fetch blocks but guarantees
+  # fresh data. Use this for explicit refresh actions, not TUI polling loops.
+  def refresh
+    @loading = true
+    output = `hut builds list 2>/dev/null | head -#{@max_builds * 10}`.strip
+    @builds = parse_builds(output)
+    @loading = false
+  end
+
+  # Queries build status in a background thread.
+  #
+  # The TUI renders continuously. Blocking on hut CLI calls freezes the
+  # interface. This method offloads the query to a thread so the UI stays
+  # responsive.
+  def refresh_async
+    Thread.new { refresh }
+  end
+
+  # Indicates whether all tracked builds succeeded.
+  #
+  # Releases should wait for CI. A single failure means the release isn't
+  # ready. Check this to gate release actions.
+  def all_passed?
+    @builds.all? { |b| b[:status] == :success }
+  end
+
+  # Indicates whether any build is still in progress.
+  #
+  # Releases should wait for CI to complete. Running builds mean the final
+  # result isn't known yet. Check this to show waiting states.
+  def any_running?
+    @builds.any? { |b| b[:status] == :running }
+  end
+
+  # Indicates whether any build failed.
+  #
+  # A failed build blocks the release. Check this to prevent premature
+  # announcements and surface CI failures.
+  def any_failed?
+    @builds.any? { |b| b[:status] == :failed }
+  end
+
+  private def parse_builds(output)
+    # Parse hut builds list output
+    builds = []
+    output.scan(/#(\d+).*?(SUCCESS|FAILED|RUNNING)/i) do |id, status|
+      builds << {
+        id:,
+        status: status.downcase.to_sym,
+      }
+    end
+    builds.first(@max_builds)
+  end
+end
+
+# Queries RubyGems.org for gem publication status.
+#
+# Releases should verify the gem is published. Checking manually is tedious.
+# Network latency makes synchronous checks slow.
+#
+# This class queries gem info from the remote registry. It refreshes in
+# background threads. It reports whether a specific version is published.
+#
+# Use it to verify gem publication after releasing.
+class RubyGemsInfo
+  # The latest published version string.
+  attr_reader :published_version
+
+  # Creates a new RubyGemsInfo query.
+  #
+  # [gem_name] The gem name to query.
+  def initialize(gem_name)
+    @gem_name = gem_name
+    @published_version = nil
+    @loading = true
+    refresh_async
+  end
+
+  # Indicates whether gem data is being fetched.
+  #
+  # The TUI shows loading indicators while fetching. Displaying stale
+  # publication status misleads users. Poll this to show spinners and detect
+  # when fresh data arrives.
+  def loading?
+    @loading
+  end
+
+  # Fetches gem publication information synchronously.
+  #
+  # The user triggers manual refresh. Synchronous fetch blocks but guarantees
+  # fresh data. Use this for explicit refresh actions, not TUI polling loops.
+  def refresh
+    @loading = true
+    output = `gem info #{@gem_name} -r 2>/dev/null`.strip
+    match = output.match(/#{@gem_name} \(([^)]+)\)/)
+    @published_version = match[1] if match
+    @loading = false
+  end
+
+  # Queries gem publication in a background thread.
+  #
+  # The TUI renders continuously. Blocking on gem info calls freezes the
+  # interface. This method offloads the query to a thread so the UI stays
+  # responsive.
+  def refresh_async
+    Thread.new { refresh }
+  end
+
+  # Compares the given version against the published version.
+  #
+  # Releases verify the gem actually published. A mismatch means the release
+  # failed or is still propagating. Check this before announcing.
+  #
+  # [version] The version string (with or without "v" prefix).
+  def published?(version)
+    @published_version == version.delete_prefix("v")
+  end
+end
+
+# Manages wiki repository commit and push status.
+#
+# Release announcements live in the wiki repo. They need to be committed and
+# pushed as part of the release process. Tracking this state manually is
+# error-prone.
+#
+# This class queries git status for announcement files. It performs commits
+# and pushes. It reports committed/pushed state for the UI.
+#
+# Use it to manage wiki announcement lifecycle.
+class WikiRepo
+  # Whether the announcement is committed.
+  attr_reader :committed
+
+  # Whether the announcement is pushed.
+  attr_reader :pushed
+
+  # Creates a new WikiRepo for an announcement.
+  #
+  # [wiki_dir] Path to the wiki repository.
+  # [announcement_path] Full path to the announcement file.
+  def initialize(wiki_dir, announcement_path)
+    @wiki_dir = wiki_dir
+    @relative_path = announcement_path.sub("#{wiki_dir}/", "")
+    @committed = false
+    @pushed = false
+    @loading = true
+    refresh_async
+  end
+
+  # Indicates whether git status is being queried.
+  #
+  # The TUI shows loading indicators while fetching. Displaying stale
+  # commit/push status misleads users. Poll this to show spinners and detect
+  # when fresh data arrives.
+  def loading?
+    @loading
+  end
+
+  # Queries git status synchronously.
+  #
+  # The user triggers manual refresh. Synchronous queries block but guarantee
+  # fresh data. Use this for explicit refresh actions, not TUI polling loops.
+  def refresh
+    @loading = true
+    Dir.chdir(@wiki_dir) do
+      # Check if committed (not in diff or untracked)
+      diff_clean = system("git diff --quiet #{@relative_path} 2>/dev/null")
+      cached_clean = system("git diff --cached --quiet #{@relative_path} 2>/dev/null")
+      tracked = system("git ls-files --error-unmatch #{@relative_path} >/dev/null 2>&1")
+      @committed = diff_clean && cached_clean && tracked
+
+      # Check if pushed
+      if @committed
+        unpushed = `git log origin/HEAD..HEAD --oneline 2>/dev/null`.strip
+        @pushed = unpushed.empty?
+      else
+        @pushed = false
+      end
+    end
+    @loading = false
+  end
+
+  # Checks wiki commit/push status in a background thread.
+  #
+  # The TUI renders continuously. Blocking on git status calls freezes the
+  # interface. This method offloads the query to a thread so the UI stays
+  # responsive.
+  def refresh_async
+    Thread.new { refresh }
+  end
+
+  # Commits the announcement file.
+  #
+  # Stages and commits the file with the given message. Does nothing in dry-run
+  # mode.
+  #
+  # [message] The commit message.
+  def commit!(message)
+    return if CLIFlags.dry_run.value
+
+    Dir.chdir(@wiki_dir) do
+      system("git", "add", @relative_path)
+      system("git", "commit", "-m", message)
+    end
+    refresh
+  end
+
+  # Pushes the wiki repo to origin.
+  #
+  # Does nothing in dry-run mode.
+  def push!
+    return if CLIFlags.dry_run.value
+
+    Dir.chdir(@wiki_dir) do
+      system("git", "push")
+    end
+    refresh
+  end
+end
+
+# Sends release announcement emails.
+#
+# Announcements go to mailing lists. macOS provides multiple ways to send:
+# MailMate's emate CLI for instant delivery, or the mailto: URL scheme for
+# manual review. Handling both paths manually is tedious.
+#
+# This class wraps email sending. It prefers emate when available. It falls
+# back to mailto: URLs. It respects dry-run mode.
+#
+# Use it to send release announcements.
+class Emailer
+  # Path to MailMate's emate CLI tool.
+  EMATE_PATH = "/Applications/MailMate.app/Contents/Resources/emate"
+
+  # Creates an Emailer.
+  #
+  # [to_address] The recipient email address.
+  # [subject] The email subject line.
+  # [body] The email body content.
+  def initialize(to_address, subject, body)
+    @to_address = to_address
+    @subject = subject
+    @body = body
+  end
+
+  # Detects whether MailMate's emate CLI is installed.
+  #
+  # The UI shows which email method will be used. Users need to know if
+  # send will be instant or require manual intervention. Check this to select
+  # the appropriate UI indicator and send method.
+  def emate_available?
+    File.executable?(EMATE_PATH)
+  end
+
+  # Sends the email via emate (instant delivery).
+  #
+  # Returns true on success. Returns true immediately in dry-run mode.
+  # Returns false if emate is not available.
+  def send_via_emate!
+    return true if CLIFlags.dry_run.value
+
+    return false unless emate_available?
+
+    IO.popen([
+      EMATE_PATH,
+      "mailto",
+      "--to",
+      @to_address,
+      "--subject",
+      @subject,
+      "--send-now",
+             ], "w") do |io|
+      io.write(@body)
+    end
+    true
+  end
+
+  # Sends the email via mailto: URL (opens mail client for review).
+  def send_via_mailto!
+    encoded_subject = URI.encode_www_form_component(@subject).gsub("+", "%20")
+    encoded_body = URI.encode_www_form_component(@body).gsub("+", "%20")
+    mailto = "mailto:#{@to_address}?subject=#{encoded_subject}&body=#{encoded_body}"
+    system("open", mailto)
+  end
+end
+
+# TUI application for managing release announcements.
+#
+# Releases involve multiple steps: previewing emails, checking CI, committing
+# wiki changes, sending announcements. Coordinating manually is error-prone.
+# Status changes asynchronously.
+#
+# This class provides a tabbed TUI. It previews emails and commits. It displays
+# a release checklist with live status. It provides actions to ship wiki
+# changes and send announcements.
+#
+# Use it to orchestrate release announcements.
+class AnnounceTUI
+  # Tab names for the UI.
+  TABS = ["Preview Email", "Preview Commit", "Announce"].freeze
+
+  # The mailing list address.
+  TO_ADDRESS = "~kerrick/ratatui_ruby-announce@lists.sr.ht"
+
+  # Creates a new AnnounceTUI.
+  def initialize
+    @current_tab = 0
+    @scroll_positions = Hash.new { |h, k| h[k] = [0, 0] } # [scroll_y, scroll_x] per tab
+    @show_help = false
+    @use_emate = nil # nil = auto-detect, true = force emate, false = force mailto
+    @content_area = nil # Stored for page scroll calculations
+    @content_block = nil # Stored for page scroll calculations
+    @current_paragraph = nil # Stored for content length calculations
+
+    # Initialize domain objects (all caching happens here)
+    @git_repo = GitRepo.new
+    @version = CLIFlags.version || @git_repo.expected_version
+
+    @announcement = Announcement.new(CLIFlags.wiki_dir.value, @version)
+    @sourcehut = SourceHut.new(max_builds: CLIFlags.builds.value)
+    @rubygems = RubyGemsInfo.new("ratatui_ruby")
+    @wiki_repo = WikiRepo.new(CLIFlags.wiki_dir.value, @announcement.path)
+    @emailer = Emailer.new(TO_ADDRESS, @announcement.subject, @announcement.body)
+  end
+
+  # Starts the TUI event loop.
+  #
+  # The announcement workflow requires user interaction. A TUI provides a
+  # responsive interface for previewing, checking status, and sending. Call
+  # this after parsing CLI arguments.
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      init_styles
+
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def init_styles
+    @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+    @ok_style = @tui.style(fg: :green)
+    @pending_style = @tui.style(fg: :yellow)
+    @error_style = @tui.style(fg: :red)
+    @border_style = @tui.style(fg: :dark_gray)
+    @title_style = @tui.style(fg: :cyan)
+    @email_client_style = @tui.style(fg: :yellow)
+  end
+
+  private def render
+    @tui.draw do |frame|
+      @tabs_area, content_area, wiki_dir_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_length(3), # Tabs
+          @tui.constraint_fill(1), # Content
+          @tui.constraint_length(1), # Wiki Dir
+        ],
+      )
+
+      # Store content area for page scroll calculations
+      @content_area = content_area
+
+      render_tabs(frame, @tabs_area)
+      render_content(frame, content_area)
+      render_wiki_dir(frame, wiki_dir_area)
+
+      # Overlay on top
+      render_help_overlay(frame) if @show_help
+    end
+  end
+
+  private def render_tabs(frame, area)
+    email_client = use_emate? ? "emate" : "mailto"
+
+    # # Dry-run indicator: gray when "no", bright bold white when "yes"
+    # dry_run_style = CLIFlags.dry_run.value ? @tui.style(fg: :white, modifiers: [:bold]) : @border_style
+    # dry_run_title = @tui.text_line(
+    #   @tui.paragraph(content: "dry-run: #{CLIFlags.dry_run.to_short}",
+    #              style: dry_run_style)
+    # )
+    dry_run_title = nil
+
+    tabs = @tui.tabs(
+      titles: TABS,
+      selected_index: @current_tab,
+      divider: @tui.text_span(content: " ▶ ", style: @border_style),
+      block: @tui.block(
+        titles: [
+          { content: "Announce #{@version}" },
+          { content: dry_run_title, position: :top, alignment: :center },
+          { content: @tui.text_line(spans: [@tui.text_span(content: email_client, style: @email_client_style)]), position: :top, alignment: :right },
+        ],
+        borders: [:all],
+        border_style: @border_style,
+      ),
+      highlight_style: @tui.style(fg: :magenta, modifiers: [:bold]),
+    )
+    frame.render_widget(tabs, area)
+  end
+
+  private def use_emate?
+    @use_emate.nil? ? @emailer.emate_available? : @use_emate
+  end
+
+  private def render_content(frame, area)
+    case @current_tab
+    when 0 then render_email_preview(frame, area)
+    when 1 then render_commit_preview(frame, area)
+    when 2 then render_checklist(frame, area)
+    end
+  end
+
+  private def render_email_preview(frame, area)
+    email_text = <<~EMAIL
+      To: #{TO_ADDRESS}
+      Subject: #{@announcement.subject}
+
+      #{@announcement.body}
+    EMAIL
+
+    lines = email_text.lines
+    content_length = lines.size
+
+    @current_paragraph = @tui.paragraph(
+      text: email_text,
+      wrap: true,
+      scroll: [scroll_y, scroll_x],
+      block: content_block("Email Preview"),
+    )
+    frame.render_widget(@current_paragraph, area)
+
+    scrollbar = @tui.scrollbar(
+      content_length:,
+      position: scroll_y,
+      orientation: :vertical,
+    )
+    frame.render_widget(scrollbar, area)
+  end
+
+  private def render_commit_preview(frame, area)
+    content = @announcement.commit_message
+    content_length = content.lines.size
+
+    @current_paragraph = @tui.paragraph(
+      text: content,
+      scroll: [scroll_y, scroll_x],
+      block: content_block("Commit Preview"),
+    )
+    frame.render_widget(@current_paragraph, area)
+
+    scrollbar = @tui.scrollbar(
+      content_length:,
+      position: scroll_y,
+      orientation: :vertical,
+    )
+    frame.render_widget(scrollbar, area)
+  end
+
+  private def render_checklist(frame, area)
+    lines = checklist_items.map { |item| checklist_line(item) }
+
+    paragraph = @tui.paragraph(
+      text: lines,
+      block: content_block("Release Checklist"),
+    )
+    frame.render_widget(paragraph, area)
+  end
+
+  private def checklist_items
+    # Build checklist from domain objects (reads cached data only)
+    # Each item shows loading if its domain object is still loading
+
+    # Build latest tag status first (needed for tag_pushed logic)
+    latest_tag_value = @git_repo.latest_tag || "None"
+    latest_tag_status = if @git_repo.tag_matches?
+      :ok
+    else
+      latest_tag_value = "#{latest_tag_value} (Should be #{@git_repo.expected_version})"
+      :error
+    end
+
+    # Git repo tag pushed check (only meaningful if tag matches)
+    tag_pushed_item = if !@git_repo.tag_matches?
+      { value: "N/A", status: :pending }
+    elsif @git_repo.loading? || @git_repo.tag_pushed.nil?
+      { value: "Loading...", status: :loading }
+    elsif @git_repo.tag_pushed
+      { value: "Yes", status: :ok }
+    else
+      { value: "No", status: :error }
+    end
+
+    # SourceHut builds
+    builds_item = if @sourcehut.loading?
+      { value: "Loading...", status: :loading }
+    else
+      builds_status = if @sourcehut.any_running?
+        :pending
+      elsif @sourcehut.all_passed?
+        :ok
+      else
+        :error
+      end
+      builds_value = @sourcehut.builds.map { |b| "##{b[:id]} #{b[:status]}" }.join(", ")
+      { value: builds_value.empty? ? "None" : builds_value, status: builds_status }
+    end
+
+    # RubyGems
+    gem_item = if @rubygems.loading?
+      { value: "Loading...", status: :loading }
+    else
+      { value: @rubygems.published_version || "Unknown", status: @rubygems.published?(@version) ? :ok : :pending }
+    end
+
+    # Wiki repo
+    wiki_committed = if @wiki_repo.loading?
+      { value: "Loading...", status: :loading }
+    else
+      { value: @wiki_repo.committed ? "Yes" : "No", status: @wiki_repo.committed ? :ok : :pending }
+    end
+
+    wiki_pushed = if @wiki_repo.loading?
+      { value: "Loading...", status: :loading }
+    else
+      { value: @wiki_repo.pushed ? "Yes" : "No", status: @wiki_repo.pushed ? :ok : :pending }
+    end
+
+    [
+      { label: "Latest tag", value: latest_tag_value, status: latest_tag_status },
+      { label: "Tag pushed", **tag_pushed_item },
+      { label: "Builds (#{@sourcehut.builds.size})", **builds_item },
+      { label: "Gem published", **gem_item },
+      { label: "Wiki committed", **wiki_committed },
+      { label: "Wiki pushed", **wiki_pushed },
+    ]
+  end
+
+  private def checklist_line(item)
+    icon = case item[:status]
+           when :ok then "✓"
+           when :error then "✗"
+           when :pending then "●"
+           when :loading then "…"
+           else "?"
+    end
+    style = case item[:status]
+            when :ok then @ok_style
+            when :error then @error_style
+            when :pending, :loading then @pending_style
+    end
+
+    @tui.text_line(spans: [
+      @tui.text_span(content: "#{icon} ", style:),
+      @tui.text_span(content: "#{item[:label]}: "),
+      @tui.text_span(content: item[:value].to_s),
+    ])
+  end
+
+  private def content_block(title)
+    # Bottom-left titles for universal controls
+    bottom_left = @tui.text_line(spans: [
+      @tui.text_span(content: "?", style: @hotkey_style),
+      @tui.text_span(content: ":Help"),
+      @tui.text_span(content: "─", style: @border_style),
+      @tui.text_span(content: "q", style: @hotkey_style),
+      @tui.text_span(content: ": Quit"),
+    ])
+
+    titles = [
+      { content: title, position: :top, alignment: :left },
+      { content: bottom_left, position: :bottom, alignment: :left },
+    ]
+
+    # Add action controls on Announce tab (bottom-right, styled red)
+    if @current_tab == 2
+      action_style = @tui.style(fg: :red, modifiers: [:bold, :underlined])
+      bottom_right = @tui.text_line(spans: [
+        @tui.text_span(content: "w", style: action_style),
+        @tui.text_span(content: ":Ship Wiki", style: @tui.style(fg: :red)),
+        @tui.text_span(content: "─", style: @border_style),
+        @tui.text_span(content: "s", style: action_style),
+        @tui.text_span(content: ":Send Email", style: @tui.style(fg: :red)),
+        @tui.text_span(content: "─", style: @border_style),
+        @tui.text_span(content: "r", style: action_style),
+        @tui.text_span(content: ":Refresh", style: @tui.style(fg: :red)),
+      ])
+      titles << { content: bottom_right, position: :bottom, alignment: :right }
+    end
+
+    # Store block for page scroll inner height calculation
+    @content_block = @tui.block(
+      titles:,
+      borders: [:all],
+      border_style: @border_style,
+      title_style: @title_style,
+    )
+  end
+
+  private def control_line(pairs)
+    spans = pairs.flat_map do |key, desc|
+      [
+        @tui.text_span(content: key, style: @hotkey_style),
+        @tui.text_span(content: ": #{desc}  "),
+      ]
+    end
+    @tui.text_line(spans:)
+  end
+
+  private def render_help_overlay(frame)
+    # Clear the area first
+    frame.render_widget(@tui.clear, frame.area)
+
+    help_text = <<~HELP
+      Navigation
+        ←/→ or h/l   Switch tabs
+        [/] or Tab   Switch tabs (alternate)
+        ↑/↓ or j/k   Scroll one line
+        PgUp/PgDn    Scroll 10 lines
+        Home/End     Scroll to top/bottom
+        Mouse wheel  Scroll 3 lines
+
+      Actions (Announce tab only)
+        w            Ship Wiki
+        s            Send Email
+        r            Refresh all data
+
+      General
+        ?            Toggle this help
+        q or Ctrl+C  Quit
+    HELP
+
+    content = @tui.paragraph(
+      text: help_text,
+      block: @tui.block(title: "Help (press Esc to close)", borders: [:all]),
+    )
+
+    center_widget = @tui.center(
+      child: content,
+      width_percent: 80,
+      height_percent: 80,
+    )
+    frame.render_widget(center_widget, frame.area)
+  end
+
+  private def render_wiki_dir(frame, area)
+    frame.render_widget(@tui.text_line(
+      alignment: :center,
+      spans: [
+        @tui.text_span(
+          content: "Wiki Dir: ",
+          style: @tui.style(
+            modifiers: [:dim]
+          )
+        ),
+        @tui.text_span(
+          content: CLIFlags.wiki_dir.to_short
+        ),
+      ]
+    ), area)
+  end
+
+  private
+
+  private def handle_input
+    event = @tui.poll_event
+
+    # When help overlay is open, only ? closes it (but q/Ctrl+C still quit)
+    if @show_help
+      case event
+      in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+        return :quit
+      in { type: :key, code: "?" } | { type: :key, code: "esc" }
+        @show_help = false
+      else
+        # Ignore all other input
+      end
+      return
+    end
+
+    case event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in { type: :key, code: "right" } | { type: :key, code: "l" } | { type: :key, code: "]" } | { type: :key, code: "tab", modifiers: ["ctrl"] }
+      @current_tab = [@current_tab + 1, TABS.size - 1].min
+    in { type: :key, code: "left" } | { type: :key, code: "h" } | { type: :key, code: "[" } | { type: :key, code: "backtab" }
+      @current_tab = [@current_tab - 1, 0].max
+    in { type: :key, code: "up" } | { type: :key, code: "k" }
+      self.scroll_y = [scroll_y - 1, 0].max
+    in { type: :key, code: "down" } | { type: :key, code: "j" }
+      self.scroll_y += 1
+    in { type: :key, code: "home" }
+      self.scroll_y = 0
+    in { type: :key, code: "end" }
+      self.scroll_y = max_scroll_y
+    in { type: :key, code: "page_up" }
+      self.scroll_y = [scroll_y - page_height, 0].max
+    in { type: :key, code: "page_down" }
+      self.scroll_y += page_height
+    in { type: :key, code: "?" }
+      @show_help = !@show_help
+    in { type: :key, code: "w" } if @current_tab == 2
+      commit_and_push_wiki
+    in { type: :key, code: "s" } if @current_tab == 2
+      send_email
+    in { type: :key, code: "r" } if @current_tab == 2
+      refresh_all
+    in { type: :mouse, kind: "scroll_down" }
+      self.scroll_y += 1
+    in { type: :mouse, kind: "scroll_up" }
+      self.scroll_y = [scroll_y - 1, 0].max
+
+    else
+      # Ignore other events
+    end
+  end
+
+  private def scroll_y = @scroll_positions[@current_tab][0]
+  private def scroll_x = @scroll_positions[@current_tab][1]
+
+  private def scroll_y=(val)
+    @scroll_positions[@current_tab][0] = val
+  end
+
+  private def scroll_x=(val)
+    @scroll_positions[@current_tab][1] = val
+  end
+
+  private def page_height
+    return 10 unless @content_area && @content_block
+
+    @content_block.inner(@content_area).height
+  end
+
+  private def content_length
+    return 0 unless @current_paragraph && @content_area && @content_block
+
+    inner_width = @content_block.inner(@content_area).width
+    @current_paragraph.line_count(inner_width)
+  end
+
+  private def max_scroll_y
+    [content_length - page_height, 0].max
+  end
+
+  # Actions
+  private def commit_and_push_wiki
+    @wiki_repo.commit!(@announcement.commit_message)
+    @wiki_repo.push!
+  end
+
+  private def send_email
+    if use_emate?
+      @emailer.send_via_emate!
+    else
+      @emailer.send_via_mailto!
+    end
+  end
+
+  private def refresh_all
+    @git_repo.refresh
+    @sourcehut.refresh
+    @rubygems.refresh
+    @wiki_repo.refresh
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  # Parse CLI options
+  script_dir = File.dirname(File.expand_path(__FILE__))
+
+  OptionParser.new do |opts|
+    opts.banner = "Usage: bin/announce_tui [OPTIONS] [VERSION]"
+
+    opts.on("-w", "--wiki-dir PATH", "Path to wiki repo") do |path|
+      CLIFlags.wiki_dir = PathFlag.new(File.expand_path(path))
+    end
+
+    opts.on("-n", "--builds N", Integer, "Number of builds to show") do |n|
+      CLIFlags.builds = IntFlag.new(n)
+    end
+
+    opts.on("-d", "--dry-run", "Stub dangerous actions (emate, git commit/push)") do
+      CLIFlags.dry_run = BoolFlag.new(true)
+    end
+
+    opts.on("-h", "--help", "Show this help") do
+      puts opts
+      exit
+    end
+  end.parse!
+
+  # Set defaults and determine version
+  CLIFlags.wiki_dir ||= PathFlag.new(File.expand_path(File.join(script_dir, "..", "..", "ratatui_ruby-wiki")))
+  CLIFlags.version = ARGV[0] # nil if not provided, will use RatatuiRuby::VERSION via GitRepo
+
+  AnnounceTUI.new.run
+end