ratatui_ruby-devtools 0.2.0 → 0.3.0

data/lib/ratatui_ruby/devtools/tasks/website/hosted_source_tree.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "fileutils"
+
+# A version's source, built with the Rakefile, tasks, and bundle of the gem
+# building the site.
+class HostedSourceTree < Data.define(:path, :gemfile) # :nodoc:
+  def self.adopt(path)
+    FileUtils.cp("Rakefile", File.join(path, "Rakefile"))
+    FileUtils.cp_r("tasks", File.join(path, "tasks")) if Dir.exist?("tasks")
+    new(path:, gemfile: File.absolute_path("Gemfile"))
+  end
+
+  # Bundler hands its lockfile down with its Gemfile, and resolves either one
+  # against the other.
+  def run(command, env = {})
+    system(env.merge("BUNDLE_GEMFILE" => gemfile, "BUNDLE_LOCKFILE" => "#{gemfile}.lock"), command, chdir: path)
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/website/index_page.rb

@@ -44,10 +44,7 @@ class IndexPage
     template_path = File.expand_path("../resources/index.html.erb", __dir__)
     template = File.read(template_path)
 
-    versions = @versions
-    branding = @branding
-    # project_name is used in the ERB
-    html_content = ERB.new(template).result(binding)
+    html_content = ERB.new(template).result_with_hash(versions: @versions, branding: @branding, project_name:)
 
     File.write(path, html_content)
   end

data/lib/ratatui_ruby/devtools/tasks/website/source_tree.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "bundler"
+require_relative "hosted_source_tree"
+
+# A version's source, exported to a directory. It runs commands with the Ruby
+# and bundle that version declares, so each version's docs build exactly as
+# they did when it was released.
+class SourceTree < Data.define(:path) # :nodoc:
+  def ruby
+    mise_ruby || ruby_version_file || gemfile_ruby || RUBY_VERSION
+  end
+
+  def run(command, env = {})
+    Bundler.with_unbundled_env do
+      system(env, "mise", "exec", "ruby@#{ruby}", "--", "sh", "-c", command, chdir: path)
+    end
+  end
+
+  # A bundle can stop installing after its release: a gem it locked gets
+  # yanked, or it names a gem by a path outside the exported source. Such a
+  # version builds with the bundle and tasks building the site instead.
+  def buildable(rdoc_floor)
+    return self if upgrade_rdoc_to(rdoc_floor) && run("bundle install --quiet")
+
+    puts "  Its own bundle won't install, so it builds with this one..."
+    HostedSourceTree.adopt(path)
+  end
+
+  private def upgrade_rdoc_to(minimum)
+    return true if locked_rdoc && locked_rdoc >= Gem::Version.new(minimum)
+
+    File.write(File.join(path, "Gemfile"), %(\ngem "rdoc", "#{minimum}"\n), mode: "a")
+    run("bundle lock --update rdoc")
+  end
+
+  private def locked_rdoc
+    version = read("Gemfile.lock")&.[](/^    rdoc \(([^)]+)\)/, 1)
+    Gem::Version.new(version) if version
+  end
+
+  private def mise_ruby
+    read("mise.toml")&.[](/^ruby\s*=\s*"([^"]+)"/, 1)
+  end
+
+  private def ruby_version_file
+    read(".ruby-version")&.strip&.then { |version| version unless version.empty? }
+  end
+
+  private def gemfile_ruby
+    read("Gemfile")&.[](/^ruby\s+["']([^"']+)["']/, 1)
+  end
+
+  private def read(name)
+    file = File.join(path, name)
+    File.read(file) if File.exist?(file)
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/website/versioned_documentation.rb

@@ -6,6 +6,7 @@
 #++
 
 require_relative "../rdoc_config"
+require_relative "source_tree"
 
 # Builds documentation for a single version.
 #
@@ -19,6 +20,12 @@ require_relative "../rdoc_config"
 #
 # Use it to build one version's documentation within a multi-version site.
 class VersionedDocumentation
+  # Earlier releases locked RDoc 6.15 or 7.0, which render some markup wrongly
+  # and predate the Aliki theme the site relies on. 7.2.0 is the oldest RDoc
+  # whose output the site accepts; a version locking a newer one builds with
+  # its own.
+  RDOC_FLOOR = "7.2.0"
+
   # Creates a VersionedDocumentation builder.
   #
   # [version] Version object to build docs for.
@@ -39,16 +46,12 @@ class VersionedDocumentation
     puts "Building documentation for #{@version.name}..."
 
     absolute_path = File.absolute_path(path)
-    gemfile_path = File.absolute_path("Gemfile")
     custom_css_path = File.absolute_path("doc/custom.css")
-    rakefile_path = File.absolute_path("Rakefile")
-    tasks_dir_path = File.absolute_path("tasks")
 
     @version.checkout(globs:) do |source_path|
-      # Copy current Rakefile and tasks into the temp directory
-      # This ensures all versions use the latest example generation logic
-      FileUtils.cp(rakefile_path, File.join(source_path, "Rakefile"))
-      FileUtils.cp_r(tasks_dir_path, File.join(source_path, "tasks"))
+      # Each version builds with its own Ruby, bundle, and tasks where it can,
+      # so upgrading RDoc or the doc tasks on trunk doesn't change its docs.
+      tree = SourceTree.new(path: source_path).buildable(RDOC_FLOOR)
 
       Dir.chdir(source_path) do
         title = "#{project_name} #{@version.name}"
@@ -56,22 +59,20 @@ class VersionedDocumentation
 
         # Use rake rerdoc to ensure copy_examples runs
         # Set environment variables to override rdoc settings
-        success = system(
+        success = tree.run(
+          "bundle exec rake rerdoc",
           {
-            "BUNDLE_GEMFILE" => gemfile_path,
             "RDOC_OUTPUT" => absolute_path,
             "RDOC_TITLE" => title,
             "RDOC_CUSTOM_CSS" => custom_css_path,
-          },
-          "bundle exec rake rerdoc"
+          }
         )
 
         # Fall back to direct rdoc call if rake fails for any reason
         unless success
           puts "  Rake task failed, falling back to direct rdoc call..."
           files = globs.flat_map { |glob| Dir[glob] }.uniq
-          system(
-            { "BUNDLE_GEMFILE" => gemfile_path },
+          tree.run(
             "bundle exec rdoc -o #{absolute_path} --main #{RDocConfig::MAIN} --title '#{title}' --template-stylesheets \"#{custom_css_path}\" #{files.join(' ')}"
           )
         end

data/lib/ratatui_ruby/devtools/tasks/website_tasks.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "erb"
+require "rake/tasklib"
+require "fileutils"
+require "tmpdir"
+require_relative "rdoc_config"
+
+# The task that builds a gem's documentation website.
+class WebsiteTasks < Rake::TaskLib # :nodoc:
+  def initialize(gem)
+    super()
+    @gem = gem
+    define
+  end
+
+  private def define
+    namespace :website do
+      desc "Build documentation for trunk (current dir) and all git tags"
+      task :build do
+        require_relative "website/website"
+
+        spec = @gem.spec
+        globs = RDocConfig::RDOC_FILES + ["*.gemspec", "doc/images/**/*", "examples/**/*"]
+
+        # Allow projects to customize via website_config.rb in their tasks/ directory
+        config = if File.exist?("tasks/website_config.rb")
+          load File.expand_path("tasks/website_config.rb", Dir.pwd)
+          WebsiteConfig::CONFIG
+        else
+          {}
+        end
+
+        Website.new(
+          at: config[:output_dir] || "www",
+          project_name: spec.name,
+          globs:,
+          assets: config[:assets] || ["doc/images"],
+          branding: config[:branding] || {}
+        ).build
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/devtools/templates/.github/workflows/build-gems.yml.erb

@@ -113,8 +113,14 @@ jobs:
           path: lib/<%= ext_name %>/<%= minor %>
 
 <%- end -%>
+      - name: Install gems
+        run: |
+          mise x -- bundle config set --local path vendor/bundle
+          mise x -- bundle config set --local frozen true
+          mise x -- bundle install
+
       - name: Build platform gem
-        run: ruby tasks/release/platform_gem.rb
+        run: mise x -- bundle exec rake release:platform_gem
 
       - name: Upload gem artifact
         uses: actions/upload-artifact@v4

data/lib/ratatui_ruby/devtools/templates/.github/workflows/ci.yml.erb

@@ -28,7 +28,7 @@ jobs:
       BINDGEN_EXTRA_CLANG_ARGS: "-include stdbool.h"
 <%- end -%>
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Override Ruby version in mise.toml
         shell: bash
@@ -61,7 +61,7 @@ jobs:
 
 <%- end -%>
       - name: Install toolchain via mise
-        uses: jdx/mise-action@v2
+        uses: jdx/mise-action@v4
 
       - name: Setup (Unix)
         if: runner.os != 'Windows'

data/lib/ratatui_ruby/devtools/templates/.gitignore.erb

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 **/.idea/
@@ -11,6 +11,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+/vendor/bundle/
 /www/
 <%- if has_rust -%>
 /ext/<%= gem_name %>/target/

data/lib/ratatui_ruby/devtools/templates/.rubocop.yml.erb

@@ -7,4 +7,4 @@ inherit_gem:
   <%= gem_name %>: lib/<%= require_path %>/rubocop.yml
 
 AllCops:
-  TargetRubyVersion: "3.2"
+  TargetRubyVersion: "3.3"

data/lib/ratatui_ruby/devtools/templates/AGENTS.md.erb

@@ -55,7 +55,7 @@ Description: <%= description %>
 
 ### Ruby Standards
 
-- Use `Data.define` for all value objects (Ruby 3.2+). (Prefer `class Foo < Data.define()` over `Foo = Data.define() do`).
+- Use `Data.define` for all value objects (Ruby 3.3+). (Prefer `class Foo < Data.define()` over `Foo = Data.define() do`).
 - Define types in `.rbs` files. Don't use `untyped` just because it's easy; be comprehensive and accurate. Do not include `initialize` in `.rbs` files; use `self.new` for constructors instead.
 - Every public Ruby class/method must be documented for humans in RDoc (preferred)--**not** YARD--or markdown files (fallback), and must have `*.rbs` types defined.
 - Every significant architectural and design decision must be documented for contributors in markdown files. Mermaid is allowed.

data/lib/ratatui_ruby/devtools/templates/CHANGELOG.md.erb

@@ -1,5 +1,5 @@
 <!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
   SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
@@ -16,3 +16,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Initial release of <%= gem_name %>
+
+[Unreleased]: https://github.com/<%= github_repo %>/tree/HEAD

data/lib/ratatui_ruby/devtools/templates/CONTRIBUTING.md.erb

@@ -23,7 +23,7 @@ Clone the repository and run the setup script for your platform.
 
 <!-- SPDX-SnippetBegin -->
 <!--
-  SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
+  SPDX-SnippetCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
   SPDX-License-Identifier: MIT-0
 -->
 ```sh
@@ -35,7 +35,7 @@ bin/setup
 
 <!-- SPDX-SnippetBegin -->
 <!--
-  SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
+  SPDX-SnippetCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
   SPDX-License-Identifier: MIT-0
 -->
 ```powershell
@@ -56,7 +56,7 @@ license checks, and the Steep type checker:
 
 <!-- SPDX-SnippetBegin -->
 <!--
-  SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
+  SPDX-SnippetCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
   SPDX-License-Identifier: MIT-0
 -->
 ```sh

data/lib/ratatui_ruby/devtools/templates/Gemfile.erb

@@ -14,12 +14,11 @@ gemspec
 gem "irb"
 gem "rake", "~> 13.0"
 
-gem "minitest", "~> 5.16"
+gem "minitest", "~> 6.0"
 
 gem "rubocop", "~> 1.21"
-gem "rubycritic", "~> 4.11"
+gem "rubycritic", "~> 5.0"
 gem "inch", "~> 0.4"
-gem "flog", "4.8.0"
 
 gem "nokogiri" # For RDoc sidebar post-processing
 gem "faker"    # For realistic example data

data/lib/ratatui_ruby/devtools/templates/README.md.erb

@@ -20,11 +20,11 @@ Announcements](https://img.shields.io/badge/forum-announcements-3b44ac.svg?logo=
 **ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
 
 > [!WARNING]
-> **<%= gem_name %>** is currently in **PRE-RELEASE**. The API will change rapidly, even between minor and patch versions.
+> **<%= gem_name %>** is in **initial development**, before 1.0. Its API can change in any release, even a patch.
 
 **[Why RatatuiRuby?](https://www.ratatui-ruby.dev/docs/trunk/doc/getting_started/why_md.html)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](https://www.ratatui-ruby.dev/docs/trunk/doc/getting_started/why_md.html) to CharmRuby, raw Rust, and Go.
 
-Please follow the [announcements](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/announcement) to stay up-to-date on new releases. See the [`trunk` branch](https://github.com/<%= github_repo %>/tree/trunk) for pre-release updates.
+Please follow the [announcements](https://forum.setdef.com/tags/c/<%= gem_name.tr('_', '-') %>/announcement) to stay up-to-date on new releases. See the [`trunk` branch](https://github.com/<%= github_repo %>/tree/trunk) for unreleased changes.
 
 ----
 
@@ -78,7 +78,7 @@ Add this line to your application's Gemfile:
 
 <!-- SPDX-SnippetBegin -->
 <!--
-  SPDX-FileCopyrightText: <%= Time.now.year %> <%= author %>
+  SPDX-SnippetCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
   SPDX-License-Identifier: MIT-0
 -->
 ```ruby
@@ -90,7 +90,7 @@ And then execute:
 
 <!-- SPDX-SnippetBegin -->
 <!--
-  SPDX-FileCopyrightText: <%= Time.now.year %> <%= author %>
+  SPDX-SnippetCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
   SPDX-License-Identifier: MIT-0
 -->
 ```bash
@@ -102,7 +102,7 @@ Or install it yourself with:
 
 <!-- SPDX-SnippetBegin -->
 <!--
-  SPDX-FileCopyrightText: <%= Time.now.year %> <%= author %>
+  SPDX-SnippetCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
   SPDX-License-Identifier: MIT-0
 -->
 ```bash
@@ -113,14 +113,14 @@ gem install <%= gem_name %>
 
 ## Usage
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+_Because this gem is in initial development, it lacks documentation. Please check the source files.
 
 For a full tutorial, see [the Quickstart](./doc/getting_started/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/concepts/application_architecture.md).
 
 
 ## Features
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+_Because this gem is in initial development, it lacks documentation. Please check the source files.
 
 
 ## Documentation

data/lib/ratatui_ruby/devtools/templates/REUSE.toml.erb

@@ -29,5 +29,5 @@ SPDX-License-Identifier = "<%= license %>"
 
 [[annotations]]
 path = 'doc/images/*'
-SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
+SPDX-FileCopyrightText = "<%= Time.now.year %> <%= copyright_holder %>"
 SPDX-License-Identifier = "CC-BY-SA-4.0"

data/lib/ratatui_ruby/devtools/templates/bin/setup.erb

@@ -17,9 +17,13 @@ mise install
 <%- if has_rust -%>
 mise x -- rustup component add rustfmt clippy
 <%- end -%>
-mise x -- pip install reuse
+mise x -- pip install 'reuse[charset-normalizer]'
 mise x -- gem install bundler:4.0.3
 
+# A gem in the per-user gem directory may have been built for another Ruby,
+# so install the bundle inside the repo instead.
+mise x -- bundle config set --local path vendor/bundle
+
 if [ "${CI:-}" = "true" ]; then
   bundle config set --local frozen 'true'
 fi

data/lib/ratatui_ruby/devtools/templates/bin/setup.ps1.erb

@@ -66,7 +66,7 @@ mise install
 mise x -- rustup target add x86_64-pc-windows-gnu
 mise x -- rustup component add rustfmt clippy
 <%- end -%>
-mise x -- python -m pip install reuse
+mise x -- python -m pip install 'reuse[charset-normalizer]'
 
 # pip installs scripts (like reuse.exe) to Python's Scripts directory,
 # which mise does not add to PATH.
@@ -91,6 +91,10 @@ CARGO_BUILD_TARGET = "x86_64-pc-windows-gnu"
 }
 gem install bundler:4.0.3
 
+# A gem in the per-user gem directory may have been built for another Ruby,
+# so install the bundle inside the repo instead.
+bundle config set --local path vendor/bundle
+
 if ($env:CI -eq "true") {
   bundle config set --local frozen true
 }

data/lib/ratatui_ruby/devtools/templates/doc/concepts/application_architecture.md.erb

@@ -9,8 +9,8 @@ Architect robust TUI applications using core library patterns and API best pract
 
 ## Core Concepts
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files._
+_Because this gem is in initial development, it lacks documentation. Please check the source files._
 
 ## Thread and Ractor Safety
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files._
+_Because this gem is in initial development, it lacks documentation. Please check the source files._

data/lib/ratatui_ruby/devtools/templates/doc/concepts/application_testing.md.erb

@@ -20,7 +20,7 @@ First, require the test helper in your test file or `test_helper.rb`:
 
 <!-- SPDX-SnippetBegin -->
 <!--
-  SPDX-FileCopyrightText: <%= Time.now.year %> <%= author %>
+  SPDX-SnippetCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
   SPDX-License-Identifier: MIT-0
 -->
 ```ruby
@@ -33,7 +33,7 @@ Then, include the module in your test class:
 
 <!-- SPDX-SnippetBegin -->
 <!--
-  SPDX-FileCopyrightText: <%= Time.now.year %> <%= author %>
+  SPDX-SnippetCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
   SPDX-License-Identifier: MIT-0
 -->
 ```ruby
@@ -46,4 +46,4 @@ end
 
 ## Writing Tests
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files and automated tests._
+_Because this gem is in initial development, it lacks documentation. Please check the source files and automated tests._

data/lib/ratatui_ruby/devtools/templates/doc/getting_started/quickstart.md.erb

@@ -17,11 +17,11 @@ See [Installation in the README](../README.md#installation) for setup instructio
 
 Here is a "Hello World" application that demonstrates the core lifecycle of a **<%= gem_name %>** app.
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+_Because this gem is in initial development, it lacks documentation. Please check the source files.
 
 #### How it works
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+_Because this gem is in initial development, it lacks documentation. Please check the source files.
 
 ## Examples
 
@@ -33,7 +33,7 @@ Focused examples for individual concepts. Each demonstrates a single concept and
 
 | Widget | What it demonstrates |
 |--------|---------------------|
-| _Automated Tests_ | _Because this gem is in pre-release, it lacks documentation. Please check the automated tests for details._ |
+| _Automated Tests_ | _Because this gem is in initial development, it lacks documentation. Please check the automated tests for details._ |
 
 ### Sample Applications
 
@@ -41,7 +41,7 @@ These larger examples combine concepts into complete applications, demonstrating
 
 | Application | Architecture | What you'll learn |
 |-------------|--------------|-------------------|
-| _Automated Tests_ | _Because this gem is in pre-release, it lacks documentation. Please check the automated tests for details._ |
+| _Automated Tests_ | _Because this gem is in initial development, it lacks documentation. Please check the automated tests for details._ |
 
 
 ## Next Steps

data/lib/ratatui_ruby/devtools/templates/ext/Cargo.toml.erb

@@ -12,7 +12,7 @@ edition = "2021"
 crate-type = ["cdylib", "staticlib"]
 
 [dependencies]
-magnus = "0.8"
+magnus = "0.9"
 ratatui = { version = "0.30", features = ["widget-calendar", "layout-cache", "unstable-rendered-line-info"] }
 
 # Optional: Arena allocation to avoid Box::leak for long-lived Ruby objects

data/lib/ratatui_ruby/devtools/templates/gemspec.erb

@@ -54,7 +54,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "ratatui_ruby"
   spec.add_development_dependency "ostruct", "~> 0.6"
-  spec.add_development_dependency "rdoc", "~> 7.0"
+  spec.add_development_dependency "rdoc", "~> 8.1"
   spec.add_development_dependency "faker", "~> 3.5"
   spec.add_development_dependency "minitest-mock"
   spec.add_development_dependency "steep"

data/lib/ratatui_ruby/devtools/templates/mise.toml.erb

@@ -4,9 +4,9 @@
 <%# REUSE-IgnoreEnd -%>
 
 [tools]
-ruby = "4.0.1"
+ruby = "4.0.7"
 <%- if has_rust -%>
-rust = "1.91.1"
+rust = "1.99.0"
 <%- end -%>
 python = "3.12"
-pre-commit = "latest"
+"pipx:pre-commit" = "latest"

data/lib/ratatui_ruby/devtools/version.rb

@@ -8,6 +8,6 @@
 module RatatuiRuby
   module Devtools
     # Current version of the ratatui_ruby-devtools gem.
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end