ratatui_ruby-devtools 0.1.0

data/README.md

@@ -0,0 +1,199 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# ratatui_ruby-devtools
+
+[![
+builds.sr.ht status](https://builds.sr.ht/~kerrick/ratatui_ruby-devtools.svg)](https://builds.sr.ht/~kerrick/ratatui_ruby-devtools?) [![
+License](https://img.shields.io/badge/License-AGPL--3.0--or--later-a2c93e)](https://spdx.org/licenses/AGPL-3.0-or-later.html) [![
+Gem Version](https://img.shields.io/gem/v/ratatui_ruby-devtools)](https://rubygems.org/gems/ratatui_ruby-devtools) [![
+Mailing List: Development](https://img.shields.io/badge/mailing_list-development-4954d5.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-devel)
+
+
+## Introduction
+
+**ratatui_ruby-devtools** provides shared development tooling for the [RatatuiRuby ecosystem](https://sr.ht/~kerrick/ratatui_ruby/). It includes Rake tasks, linters, license enforcement, and build tooling used across all RatatuiRuby gems.
+
+This is a **non-runtime** gem. It provides build tooling—not application features. Add it to your `:development` group only.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+group :development do
+  gem "ratatui_ruby-devtools"
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+And then execute:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+bundle install
+```
+<!-- SPDX-SnippetEnd -->
+
+
+## Usage
+
+In your `Rakefile`:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+require "bundler/gem_tasks"
+require "ratatui_ruby/devtools"
+
+RatatuiRuby::Devtools.install!
+
+task default: %i[lint]
+```
+<!-- SPDX-SnippetEnd -->
+
+This imports all devtools rake tasks into your project.
+
+
+## Provided Rake Tasks
+
+### Linting
+
+| Task | Description |
+|------|-------------|
+| `rake lint` | Run all lint tasks |
+| `rake lint:fix` | Auto-fix all linting issues |
+| `rake rubocop` | Run RuboCop |
+| `rake rubycritic` | Run RubyCritic |
+| `rake doc:suggest` | Suggest documentation improvements |
+
+### License Enforcement
+
+| Task | Description |
+|------|-------------|
+| `rake license:all` | Run all license tasks |
+| `rake license:headers:all` | Ensure all files have SPDX headers |
+| `rake license:new` | Apply license headers to changed files only |
+| `rake reuse:lint` | Check REUSE/SPDX compliance |
+| `rake reuse:fix` | Add missing SPDX headers |
+
+### Version Bumping
+
+| Task | Description |
+|------|-------------|
+| `rake bump:major` | Bump major version |
+| `rake bump:minor` | Bump minor version |
+| `rake bump:patch` | Bump patch version |
+| `rake bump:exact[0.1.0]` | Set exact version |
+
+
+## Executables
+
+### `bin/agent_rake`
+
+An AI-friendly wrapper for `bundle exec rake` that captures all output and only shows failure summaries.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+bin/agent_rake           # Run default task
+bin/agent_rake test      # Run specific task
+```
+<!-- SPDX-SnippetEnd -->
+
+### `bin/consolidate_md`
+
+Merge multiple markdown files into one, adjusting heading levels.
+
+### `bin/hbs`
+
+Handlebars templating utility.
+
+
+## Templates
+
+Devtools includes templates for scaffolding new ecosystem gems:
+
+| Template | Purpose |
+|----------|---------|
+| `AGENTS.md.erb` | AI agent instructions |
+| `.pre-commit-config.yaml` | Pre-commit hooks |
+| `Rakefile.erb` | Standard Rakefile |
+| `sourcehut.rake.erb` | SourceHut CI task |
+| `build.yml.erb` | SourceHut build manifest |
+| `gemspec.erb` | Standard gemspec |
+| `bin/setup.erb` | Setup script |
+| `mise.toml.erb` | Toolchain versions |
+| `REUSE.toml.erb` | License annotations |
+| `.gitignore.erb` | Git ignores |
+| `.rubocop.yml.erb` | RuboCop config |
+
+Access templates via:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+RatatuiRuby::Devtools.templates_path
+# => "/path/to/devtools/templates"
+```
+<!-- SPDX-SnippetEnd -->
+
+
+## Configuration
+
+Tasks auto-discover gem configuration from your `*.gemspec`. Override if needed:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+RatatuiRuby::Devtools.gem_name = "my_gem"
+RatatuiRuby::Devtools.version_file = "lib/my_gem/version.rb"
+```
+<!-- SPDX-SnippetEnd -->
+
+Environment variables for REUSE tasks:
+
+| Variable | Default |
+|----------|---------|
+| `REUSE_COPYRIGHT` | `Kerrick Long <me@kerricklong.com>` |
+| `REUSE_CODE_LICENSE` | `AGPL-3.0-or-later` |
+| `REUSE_DOC_LICENSE` | `CC-BY-SA-4.0` |
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on [sourcehut](https://sourcehut.org) at https://sr.ht/~kerrick/ratatui_ruby/. This project is intended to be a safe, productive collaboration, and contributors are expected to adhere to the [Code of Conduct](https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md).
+
+Want to help develop **ratatui_ruby-devtools**? Check out the [contribution guide on the wiki](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md).
+
+
+## Copyright & License
+
+**ratatui_ruby-devtools** is copyright 2026, Kerrick Long.
+
+The gem is [AGPL-3.0-or-later](./LICENSES/AGPL-3.0-or-later.txt): you may use it freely, but you must share changes you make. Documentation is [CC-BY-SA-4.0](./LICENSES/CC-BY-SA-4.0.txt). Code snippets in documentation are [MIT-0](./LICENSES/MIT-0.txt) (no attribution required).
+
+This program was created with significant assistance from multiple LLMs. The process was human-controlled through creative prompts, with human contributions to each commit. See commit footers for model attribution. [declare-ai.org](https://declare-ai.org/1.0.0/creative.html)

data/REUSE.toml

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+version = 1
+
+[[annotations]]
+path = 'Gemfile.lock'
+SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "CC0-1.0"
+
+# Template files contain ERB that generates SPDX headers for consumer gems.
+# The templates themselves are AGPL-3.0-or-later, while the generated output
+# will have the appropriate license for the consumer gem.
+[[annotations]]
+path = 'lib/ratatui_ruby/devtools/templates/**/*.erb'
+SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
+

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "bundler/gem_tasks"
+require_relative "lib/ratatui_ruby/devtools"
+
+RatatuiRuby::Devtools.install!
+
+task default: %i[lint]

data/bin/agent_rake

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Development wrapper for agent_rake executable.
+# Loads the local gem via Bundler, then delegates to exe/agent_rake.
+
+require "bundler/setup"
+load File.expand_path("../exe/agent_rake", __dir__)

data/bin/announce

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Development wrapper for announce executable.
+# Loads the local gem via Bundler, then delegates to exe/announce.
+
+require "bundler/setup"
+load File.expand_path("../exe/announce", __dir__)

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require "bundler/setup"
+require "ratatui_ruby/devtools"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/consolidate_md

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Development wrapper for consolidate_md executable.
+# Loads the local gem via Bundler, then delegates to exe/consolidate_md.
+
+require "bundler/setup"
+load File.expand_path("../exe/consolidate_md", __dir__)

data/bin/hbs

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Development wrapper for hbs executable.
+# Loads the local gem via Bundler, then delegates to exe/hbs.
+
+require "bundler/setup"
+load File.expand_path("../exe/hbs", __dir__)

data/bin/setup

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+if command -v mise >/dev/null 2>&1; then
+  mise install
+  mise x -- pip install reuse
+  mise x -- bundle install
+  pre-commit install
+else
+  echo "mise isn't installed. Please install it to continue." >&2
+  exit 1
+fi

data/doc/contributors/documentation_style.md

@@ -0,0 +1,121 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Documentation Style Guide
+
+This project follows a strict and specific documentation style designed to be helpful, readable, and consistent. It combines the structural clarity of Christopher Alexander's Pattern Language with the prose style of William Zinsser's *On Writing Well* and the usability of the U.S. Federal Plain Language Guidelines.
+
+**All agents and contributors must adhere to these standards.**
+
+## 1. Core Philosophy
+
+*   **Context, Problem, Solution (Alexandrian Form):** Do not just say *what* a class does. Explain *why* it exists. Start with the context, state the problem (the pain point without this tool), and then present the class as the solution.
+*   **Prose Style (Zinsser/Klinkenborg):** Use short, punchy sentences. Use active voice. Cut unnecessary words. Avoid "allow," "enable," "provide," "support," "functionality," and "capability" where possible. Weak verbs hide the action. Strong verbs drive the sentence.
+*   **User-Centric (Plain Language):** Speak directly to the user ("You"). Don't abstract them away ("The developer"). Focus on their goals and how this tool helps them achieve those goals.
+*   **Tone (Supportive and Authoritative, not Hostile or Prescriptive):** Avoid "must," "requires," "need to," or "mandatory." These words sound bossy. Treat the user as a capable peer. Instead of "You must do X," use imperative "Do X" or cause-and-effect "X ensures Y."
+
+## 2. Class Documentation
+
+Every public class must begin with a **Context-Problem-Solution** narrative.
+
+### Structure
+
+1.  **Summary Line:** A single line explaining the class's role.
+2.  **Context (Narrative):** A short paragraph establishing the domain or situation.
+3.  **Problem (Narrative):** A sentence or two identifying the specific difficulty, complexity, or "pain" the user faces in this context without the widget.
+4.  **Solution (Narrative):** A sentence explaining how this widget solves that problem, often starting with "This widget..." or "Use it to...".
+5.  **Usage (Narrative):** A concrete "Use it to..." sentence listing common applications.
+6.  **Example:** A comprehensive, copy-pasteable code example using `=== Examples`. Provide **multiple** examples to cover different use cases (e.g., basic usage vs. advanced configuration).
+
+### Example
+
+**Bad (Generic/Descriptive):**
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# A widget for displaying list items.
+# It allows the user to select an item from an array of strings.
+# Supports scrolling and custom styling.
+```
+<!-- SPDX-SnippetEnd -->
+
+**Good (Alexandrian/Zinsser/Plain Language):**
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# Displays a selectable list of items.
+#
+# Users need to choose from options. Menus, file explorers, and selectors are everywhere.
+# Implementing navigation, highlighting, and scrolling state from scratch is tedious.
+#
+# This widget manages the list. It renders the items. It highlights the selection. It handles the scrolling window.
+#
+# Use it to build main menus, navigation sidebars, or logs.
+```
+<!-- SPDX-SnippetEnd -->
+
+## 3. Method and Attribute Documentation
+
+### Prose Style
+
+*   **Attributes:** Use concise noun phrases. Avoid "This attribute returns..." or "Getter for...".
+    *   *Bad:* "This is the width of the widget."
+    *   *Good:* "Width of the widget in cells."
+*   **Methods:** Use active, third-person present tense verbs.
+    *   *Bad:* "Will calculate the total."
+    *   *Good:* "Calculates the total."
+*   **Context:** For complex methods, you may use a condensed version of the Context-Problem-Solution pattern, but keep it brief.
+
+### Syntax Standards
+
+*   **Examples:** All public methods must include at least one usage example. Use `=== Example`.
+*   **Attributes:** Use `attr_reader` with documentation comments immediately preceding them.
+*   **Parameters:** Use strict RDoc definition lists `[name] description` for parameters in the `initialize` method.
+*   **Formatting:** Use `<tt>` tags for code literals, symbols, and values (e.g., `<tt>:vertical</tt>`).
+    *   Do **not** use backticks (\`) or markdown-style links `[text](url)`. RDoc does not render them correctly in all contexts.
+    *   Do **not** use smart quotes.
+
+### Example
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+  # The styling to apply to the content.
+  attr_reader :style
+
+  # Creates a new List.
+  #
+  # [items] Array of Strings.
+  # [selected_index] Integer (nullable).
+  def initialize(items: [], selected_index: nil)
+    super
+  end
+```
+<!-- SPDX-SnippetEnd -->
+
+## 4. RDoc Specifics
+
+*   **No Endless Methods:** Do **not** use Ruby 3.0+ endless method definitions (`def foo = bar`). RDoc currently has a bug where it fails to correctly parse the end of the method, causing subsequent methods to be nested incorrectly in the documentation tree. Always use standard `def ... end` blocks.
+*   **No YARD:** Do not use `@param`, `@return`, or other YARD tags. Use standard RDoc formats.
+*   **Directives:** Use `:nodoc:` for private or internal methods that should not appear in the API docs.
+*   **Headings:** Use `===` for section headers like `=== Examples`.
+
+## 5. Checklist for Agents
+
+Before finalizing documentation, ask:
+1.  Did I explain the *problem* this code solves?
+2.  Are my sentences short and active? (Did I remove "allows the user to"?)
+3.  Is the code example valid and copy-pasteable?
+4.  Did I use `<tt>` for symbols and code values?
+5.  Did I document every attribute and parameter?

data/doc/custom.css

@@ -0,0 +1,22 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+.theme-toggle {
+  margin-left: 0 !important;
+}
+
+/* Terminal Previews (Native PNGs)
+ * The images already contain the window chrome and shadows.
+ * We just need to center them and ensure they scale down on mobile.
+ */
+img[src*="images/"] {
+  display: block;
+  margin: 2em auto;
+}

data/exe/agent_rake

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# ==============================================================================
+# bin/agent_rake: The AI-Friendly Build Wrapper
+# ==============================================================================
+#
+# WHY THIS EXISTS:
+# 1. Noise Reduction for AI Agents:
+#    Compiling Rust extensions (Via Cargo) and installing gems produces massive
+#    amounts of "noisy" output (compilation steps, warnings, progress bars).
+#    This noise fills up an AI agent's limited context window, truncating the
+#    actual error message we need to fix.
+#
+# 2. Atomic Dump vs. Streaming:
+#    Humans like "Streaming" (seeing lines appear in real-time).
+#    Agents need an "Atomic Dump" of *only* the failure.
+#    If we stream, the agent's context fills with noise before the failure occurs.
+#    By capturing to a file, we can discard the noise and only show the failure.
+#
+# 3. Merging Stdout/Stderr:
+#    We merge stdout and stderr because:
+#    - Minitest prints failures to stdout, not stderr.
+#    - We need to preserve temporal order (e.g., a "warning" in stderr right
+#      before a "failure" in stdout).
+#
+# 4. Transparent Passthrough:
+#    This script wraps `bundle exec rake`. Any arguments you pass to this script
+#    (e.g., `bin/agent_rake test:ruby`) are passed directly to rake.
+#    Environment variables (e.g., `TEST=...`) are inherited naturally.
+#
+# ==============================================================================
+
+require "fileutils"
+require "shellwords"
+
+# Persist the log file so it can be inspected manually if summarization fails.
+# We do NOT use a Tempfile because we want the log to survive script exit.
+LOG_FILE = File.expand_path(File.join(__dir__, "..", "tmp", "agent_rake.log"))
+FileUtils.mkdir_p(File.dirname(LOG_FILE))
+
+cmd = "bundle exec rake #{ARGV.shelljoin}"
+
+# Run the command, redirecting everything to the log file.
+# This silences the terminal output completely unless there's a failure.
+success = system(cmd, %i[out err] => LOG_FILE)
+
+if success
+  puts "PASS"
+  exit 0
+else
+  puts "FAIL"
+  puts "Full output saved to: #{LOG_FILE}"
+  puts "---"
+  puts "Failure Summary (extracted from log):"
+  puts
+
+  begin
+    # aggressively force UTF-8 to avoid "incompatible encoding regexp match" errors
+    # when the log contains binary data or weird sequences from Cargo.
+    raw_content = File.binread(LOG_FILE)
+    content = raw_content.encode("UTF-8", invalid: :replace, undef: :replace, replace: "?")
+
+    # Try to extract meaningful failure information
+    if content.include?("Failure:") || content.include?("Error:")
+      # Regex explanation:
+      # Look for a line starting with "  1) Failure:"
+      # Capture everything until the next "  N) Failure:" or End Of String (\Z).
+      # /m (multiline) mode allows . to match newlines.
+      failures = content.scan(/(?:^\s*\d+\) (?:Failure|Error):.*?(?=\n\s*\d+\) (?:Failure|Error):|\Z))/ms)
+
+      if failures.any?
+        puts failures.join("\n")
+      else
+        # Fallback: Print lines containing "Error" or "Failure" with context
+        puts content.lines.grep(/(Failure:|Error:|error\[)/).first(20).join
+        puts "... (summarization failed to find full blocks, see log for more)"
+      end
+    else
+      # If no standard Ruby/Minitest failure patterns found, it might be a build error.
+      # Dump the last 50 lines which usually contain the crash/build error.
+      puts "No structured failure pattern detected. Dumping last 50 lines:"
+      puts content.lines.last(50).join
+    end
+  rescue => e
+    puts "Error summarizing log file: #{e.class}: #{e.message}"
+  end
+
+  puts "Use `grep` or run `cat #{LOG_FILE}` to see details."
+  exit 1
+end