rich-ri 0.1.0

data/docs/development.md

@@ -0,0 +1,110 @@
+# Development checks
+
+Use [Contributing](../CONTRIBUTING.md) for the usual edit, test and PR workflow.
+The commands here cover CI, dependency compatibility and performance work.
+
+## Documentation checks
+
+For documentation changes, run:
+
+```sh
+bundle exec rake docs:check
+```
+
+This checks local links, spelling, the generated manual and runnable examples
+from the usage and configuration guides. It does not need the optional shells
+or system manual tools.
+
+CI uses these checks for changes limited to Markdown guides in `docs`, the
+configuration example, PNG comparison images, the PR template and the root README,
+architecture, contribution, changelog, security and code of conduct documents.
+Pull requests also run the commit checks.
+
+Code, dependencies, scripts, workflows, test fixtures, the generated manual and
+unrecognized paths run the full suite. CI considers the entire PR, including
+deleted and renamed files; an unavailable comparison also runs the full suite.
+The required `ci` check verifies that every expected job succeeded before a
+change can merge.
+
+Releases always run the full suite, including workflow dry runs. Scheduled runs
+check the dependency advisory database.
+
+## Shell tests
+
+Run completion tests in all three shells with:
+
+```sh
+bundle exec rake test:shells
+```
+
+The task uses local Bash, Zsh and Fish when all are available and Bash can load
+bash-completion 2.x. Otherwise, it uses a running Docker engine or, if unavailable,
+Podman. `bundle exec rake check` includes this task and requires every shell test
+to pass. The shorter `bundle exec rake` run skips unavailable local integrations.
+
+To run in an isolated environment even when the shells are installed:
+
+```sh
+bundle exec rake test:shells:container
+```
+
+The first build downloads the image and installs the locked bundle; later builds
+reuse those layers. Only the project files needed for testing are copied into the
+image. Tests run as an unprivileged user with temporary storage and no network.
+The container uses its pinned Linux/Ruby environment and `Gemfile.lock`, regardless
+of the host Ruby version. CI checks this route as well as native shell integrations
+on Linux and macOS.
+
+Set `RICH_RI_CONTAINER_RUNTIME=docker` or `RICH_RI_CONTAINER_RUNTIME=podman` to
+select an engine when running in a container. For example:
+
+```sh
+RICH_RI_CONTAINER_RUNTIME=podman bundle exec rake test:shells:container
+```
+
+## Compatibility checks
+
+The main `Gemfile.lock` fixes development dependencies. CI also resolves current
+versions with `bundle update` in a fresh checkout. Run that check in a separate
+checkout to keep your working lockfile intact.
+
+To test the minimum runtime dependencies, use Ruby 3.4 with Bash, Zsh, Fish and
+bash-completion 2.x installed locally, then run:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/legacy.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/legacy.gemfile bundle exec ruby -rrdoc/rdoc -e \
+  'RDoc::RDoc.new.document(ARGV)' -- --ri --quiet --op tmp/legacy-ri test/fixtures/example.rb
+BUNDLE_GEMFILE=gemfiles/minimum.gemfile bundle install
+LEGACY_RI_STORE="$PWD/tmp/legacy-ri" BUNDLE_GEMFILE=gemfiles/minimum.gemfile \
+  RICH_RI_REQUIRE_SHELLS=1 bundle exec ruby bin/test-compatibility
+```
+
+The first bundle generates a store using RDoc 6.14. The second runs the runtime
+tests using the minimum direct dependencies compatible with RDoc 8.1, including
+lookup and completion against that older store. Maintenance-only tests and the
+optional server/profiler modes use the main bundle; missing-gem behavior is tested
+with both bundles. `LEGACY_RI_STORE` selects the test store; `RICH_RI_REQUIRE_SHELLS=1`
+requires all shell integrations to be available. This check uses the selected
+minimum bundle and local shells; the container task uses the main locked bundle.
+
+When raising a runtime dependency floor, update the minimum Gemfile and
+[compatibility policy](compatibility.md) in the same change.
+
+## Performance
+
+```sh
+bundle exec ruby bin/benchmark --output /tmp/rich-ri-before.json
+# Make the change, then measure again on the same machine and Ruby.
+bundle exec ruby bin/benchmark --compare /tmp/rich-ri-before.json
+```
+
+The benchmark measures full CLI startup, rendering and completion against a
+temporary RI store built from a repository fixture. It discards one warm-up
+invocation and reports the median of five runs. `--iterations=N` selects 1 to 50
+runs; `--output=FILE` saves the JSON report.
+
+Comparison exits unsuccessfully when a case slows by both more than 30% and
+50 ms. Compare under similar load with the same Ruby and dependency versions;
+small timing differences are not meaningful. CI uploads a `benchmark` artifact
+for each quality run so a reviewer can inspect measurements across changes.

data/docs/images/README.md

@@ -0,0 +1,29 @@
+# README comparison
+
+`ri-vs-rich-ri.png` compares the original `ri -f ansi` formatter with rich-ri's
+default terminal theme. Both panels show the complete installed `Object#then`
+documentation, from the first line to the last. Its Ruby examples include method
+chains, blocks, strings, constants and symbols.
+
+The renderer captures both commands with the project's Bundler environment and
+the same 58-column width, then displays their actual ANSI output using the same
+dark terminal palette and monospace font. It preserves bold, italic,
+underline and reverse-video attributes, including the original formatter's
+inline-code styling. Long code and output lines soft-wrap at the panel width.
+Every output line is included. The displayed commands show normal interactive
+usage; capture adds `--no-pager --width=58` to both, and
+`--no-config --color=always` to rich-ri.
+
+To refresh the image, install the bundle, Ruby core RI documentation,
+ImageMagick with SVG support and a monospace font with bold and italic faces.
+The script uses Ruby's standard libraries to capture the output and generate
+an SVG, then ImageMagick to convert it to PNG.
+
+```sh
+ruby docs/images/render_comparison.rb
+```
+
+The script clears reader configuration overrides and saves the full raw captures
+and SVG in a temporary directory printed at the end. Its footer records the Ruby
+and RDoc versions. Review the PNG before committing it; documentation text can
+change between Ruby versions.

data/docs/maintenance.md

@@ -0,0 +1,105 @@
+# Maintenance
+
+## Release infrastructure
+
+`bundle exec rake github:verify` checks branch and tag protections, required CI
+checks, the release environment and security settings. `rake github:setup`
+applies the project policy. Both require repository administrator access.
+
+Publication uses [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/).
+The publisher must match repository `hvpaiva/rich-ri`, workflow `release.yml`
+and environment `release`. Update that binding in RubyGems if the integration
+changes. `github:verify` checks GitHub settings only.
+
+## Release
+
+From a clean, up-to-date `main`, with `gh` authenticated and Git signing configured:
+
+```sh
+bin/release X.Y.Z --push
+```
+
+The command prepares the version, changelog and manual, runs the checks, opens a
+release PR, waits for CI, merges, and pushes a signed tag for the merge commit.
+It then watches the Release workflow. Omit `--push` to stop at the PR;
+`--dry-run` previews preparation without writing files or publishing.
+
+The workflow reruns CI, validates the tag and branch ancestry, builds one gem,
+and tests installation of that file. It records a SHA-256 checksum and a GitHub
+build attestation. The publication and GitHub Release jobs download that artifact
+and verify its checksum. RubyGems authentication uses short-lived OIDC credentials.
+`rake release` publishes the verified artifact and refuses local execution.
+
+To rehearse the workflow without publishing a gem or creating a GitHub Release:
+
+```sh
+gh workflow run release.yml --ref main -f dry_run=true
+```
+
+Inspect the run in Actions. The rehearsal exercises CI, packaging, installation,
+artifact transfer and attestation; it does not request RubyGems credentials.
+It cannot validate the publisher's authentication with RubyGems.
+
+## Verify a download
+
+Download the gem and `SHA256SUMS` from its GitHub Release, then run:
+
+```sh
+sha256sum --check SHA256SUMS
+gh attestation verify rich-ri-X.Y.Z.gem --repo hvpaiva/rich-ri --source-ref refs/tags/vX.Y.Z
+```
+
+On macOS, use `shasum -a 256 --check SHA256SUMS`. The attestation binds the artifact
+to its source and workflow. Release tags and published GitHub releases are immutable.
+
+## Recover an interrupted release
+
+Run the same `bin/release` command again. It inspects existing branches, PRs,
+commits and tags before continuing. It never replaces an existing tag.
+
+If a workflow failed before publication, correct the problem and follow the
+printed retry command. If RubyGems publication succeeded and only GitHub Release
+creation failed, retry that job alone. When the publication result is uncertain,
+check RubyGems before retrying: an accepted version must not be pushed again.
+
+## Urgent fixes
+
+Only the latest released version receives fixes. If `main` contains unfinished
+work for the next release, start a hotfix branch at the latest released tag.
+For example, to fix `0.2.0` while `main` is preparing `0.3.0`:
+
+```sh
+git switch -c hotfix/0.2 v0.2.0
+git push -u origin hotfix/0.2
+```
+
+Create a topic branch from it and submit the fix as a PR against `hotfix/0.2`.
+Hotfix branches have the same protections as `main`. After the fix is merged,
+update the local hotfix branch and run:
+
+```sh
+bin/release 0.2.1 --branch hotfix/0.2 --push
+```
+
+The release must match the branch's major and minor version. Bring the fix and
+release notes back to `main` through a separate PR, preserving changes still under
+`Unreleased` and keeping dated changelog entries newest first.
+
+If a published version must be withdrawn, publish a fixed version first when
+possible. Explain the withdrawal in its changelog entry, then use
+`gem yank rich-ri -v X.Y.Z` with your personal RubyGems credentials and MFA.
+Trusted publishing only grants push access. A withdrawn version cannot be reused;
+publish a new version number for the replacement.
+
+## Dependencies and access
+
+Dependabot proposes gem and test-image updates weekly and action updates monthly. Review the
+upstream changes and run the same checks as other PRs. A runtime dependency change
+may need a changelog entry even when Dependabot supplied `skip-changelog`.
+Update `gemfiles/minimum.gemfile` when raising a supported dependency floor.
+The scheduled audit checks the lockfile for known vulnerabilities.
+
+Review repository administrators, RubyGems owners and publisher configuration
+when maintainers change. Keep account recovery methods current and transfer both
+services when handing over the project. Review changes to release code and
+workflows with particular care; they run with publication or attestation permissions.

data/docs/shell-completion.md

@@ -0,0 +1,51 @@
+# Shell completion
+
+Completion reads the active Ruby's RI stores, including sources selected in your
+configuration file, `RI` or `--doc-dir`. It makes no network requests. It suggests
+installed classes, methods, pages, options, theme names and style roles, with
+descriptions where available. Invalid configuration or unavailable stores prevent
+documentation-name suggestions; options and theme values remain available. Run
+`rich-ri --show-config` to diagnose configuration errors.
+
+## Bash
+
+Load bash-completion 2.x in your shell, then install the lazy-loaded script:
+
+```sh
+mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions"
+rich-ri --completion=bash > "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions/rich-ri"
+```
+
+To load it in the current shell, run `source <(rich-ri --completion=bash)`.
+
+## Zsh
+
+After `autoload -Uz compinit && compinit` in your `.zshrc`, add:
+
+```zsh
+source <(rich-ri --completion=zsh)
+```
+
+## Fish
+
+```fish
+mkdir -p "$__fish_config_dir/completions"
+rich-ri --completion=fish > "$__fish_config_dir/completions/rich-ri.fish"
+```
+
+## Use the short name ri
+
+For Bash, add these lines after loading bash-completion:
+
+```bash
+alias ri='rich-ri'
+source <(rich-ri --completion=bash)
+complete -o filenames -F _rich_ri ri
+```
+
+For Zsh, add `alias ri='rich-ri'` after the completion setup. Zsh expands aliases
+for completion by default. In Fish, use `alias ri rich-ri` in your configuration;
+Fish aliases inherit completions from the wrapped command.
+
+Bash and Fish install a copy of the script; repeat the installation after upgrading
+rich-ri. The Zsh setup loads the current script when a new shell starts.

data/docs/troubleshooting.md

@@ -0,0 +1,95 @@
+# Troubleshooting
+
+## A page is missing
+
+Check `rich-ri --list` for known classes and `rich-ri --list-doc-dirs` for the
+directories being searched. Try `ri NAME` with the original reader as well.
+If you use an alias, `command ri NAME` bypasses it in Bash and Zsh.
+
+For a gem installed without documentation, run `gem rdoc GEM_NAME --ri`.
+For Ruby's core classes, install the documentation package supplied by your Ruby
+manager or operating system. Switch to the intended Ruby before generating or
+reading documentation: each installation has its own stores.
+
+See [documentation sources](usage.md#documentation-sources-and-missing-pages)
+to read documentation from a project directory.
+
+## An RI cache has an incompatible format
+
+RDoc uses different serialized markup representations on Ruby 3 and Ruby 4.
+Keep documentation with the Ruby installation that generated it. Regenerate gem
+documentation with `gem rdoc GEM_NAME --ri` under the Ruby you are using now.
+
+For core documentation, obtain the source for that Ruby version, then generate a
+new RI store with the current RDoc. For example, from the Ruby source directory:
+
+```sh
+rdoc --ri --op doc/ri
+rich-ri --no-standard-docs --doc-dir doc/ri Array
+```
+
+Use [doc_dirs](configuration.md#file-keys) to keep using the new store. Do not
+copy a cache from another Ruby installation as a substitute for regeneration.
+
+## Colors are missing or hard to read
+
+Colors are enabled automatically on a terminal. `NO_COLOR`, `TERM=dumb` and
+redirected output disable automatic colors. Try `rich-ri --color=always NAME`
+to force them, or `rich-ri --no-color NAME` for plain output.
+
+The default theme uses the terminal's palette. Adjust a role such as
+`--style='comment=bright_black'`, or select `--theme=light` or `--theme=dark`.
+[Themes and styles](configuration.md#themes-and-styles) describes persistent settings.
+
+Ruby highlighting is built in. Shell examples and other tagged languages need
+bat on `PATH`; confirm it with `bat --version`. If bat fails or cannot safely
+highlight an example, that example stays plain. A failure disables bat for the
+rest of the page. `--shell-theme` and `--bat-theme` must name an installed bat
+theme; list them with `bat --list-themes`.
+
+## The pager behaves differently
+
+Try `rich-ri --no-pager NAME` to isolate the reader from the pager.
+`RI_PAGER` takes precedence over `PAGER`; a configured pager command and
+`--pager-command` can also select it. Check the effective settings with
+`rich-ri --show-config`. For less, rich-ri adds `-R` so ANSI colors are displayed.
+
+## An optional RDoc mode cannot start
+
+`--server` needs the `webrick` gem; `--profile` needs the `profile` gem. Install
+the named gem with the active Ruby, then repeat the command. For example,
+`gem install webrick` enables the web server. With `bundle exec`, include the
+gem in the current Gemfile as well.
+
+These gems are not required for terminal lookup or completion. See
+[optional RDoc modes](usage.md#optional-rdoc-modes) for their behavior.
+
+## Configuration prevents startup
+
+`rich-ri --config-path` prints the selected file. `--no-config` skips that file;
+environment variables still apply. Help and version output remain available
+even when the file contains invalid YAML or settings.
+
+See [configuration troubleshooting](configuration.md#troubleshooting) for
+precedence, YAML types and path handling.
+
+## Tab completion is missing
+
+Follow the setup for your shell in [shell completion](shell-completion.md).
+After changing a shell startup file, open a new shell or load the file again.
+For an alias, include the alias setup from that guide.
+
+If options complete but documentation names do not, check `--show-config` and
+`--list-doc-dirs`. Invalid settings or an unreadable RI store prevent name
+discovery. Bash and Fish completion scripts should be reinstalled after an upgrade.
+
+## Report a problem
+
+Include the command, expected result, actual result and a small document that
+reproduces it. Provide `rich-ri --version`, `ruby --version`, your operating
+system, shell and terminal, and the output of `gem list --local rdoc prism reline`.
+For shell highlighting, include `bat --version` too.
+
+Review any configuration output before sharing it; pager arguments and file
+paths can contain private information. Open a [bug report](https://github.com/hvpaiva/rich-ri/issues/new?template=bug.yml).
+Use the [private security channel](../SECURITY.md) for vulnerabilities.

data/docs/usage.md

@@ -0,0 +1,147 @@
+# Reading documentation
+
+Names follow RI conventions. Use `Class#method` for instance methods,
+`Class::method` for class methods, and `Class.method` to search both.
+Quote names containing shell punctuation, such as `rich-ri 'Array.[]'`.
+Write long options in full; abbreviations are not accepted.
+
+Run `rich-ri` without arguments for RI's interactive lookup. Its Tab completion
+is extended with documentation pages and method prefixes such as `String#`,
+`String.` and `String::`; submit an empty line to leave. With shell completion
+installed, you can also find classes, methods, pages and options before running a command:
+
+```text
+rich-ri Str<Tab>
+rich-ri String#<Tab>
+rich-ri String.<Tab>
+rich-ri ruby:<Tab>
+rich-ri --<Tab>
+```
+
+In less, use `/` to search, `n` for the next match, Space for the next page and
+`q` to return. `--no-pager` writes directly to stdout.
+
+Headings keep their RDoc level markers (`=`, `==`, through `======`), in the
+same style as the heading text. Horizontal separators use plain hyphens in a
+muted style. Search for `^=== ` to find level-three headings or `^---` to find
+separators, then use `n` and `N` to move between matches. These markers remain
+available with colors disabled.
+
+```sh
+rich-ri --all Array
+rich-ri --width=72 String#scan
+rich-ri --color=always Array#map | less -R
+rich-ri --no-color Hash
+rich-ri --format=markdown Array#map
+```
+
+`--format` selects an original RDoc formatter. Otherwise, disabling colors
+preserves rich-ri's page layout. Code blocks keep their content and indentation;
+prose wraps by visible terminal width, including wide Unicode characters.
+
+## Documentation sources and missing pages
+
+rich-ri reads installed documentation; it does not download documentation or
+generate it while you browse. `rich-ri --list-doc-dirs` shows the searched paths,
+and `rich-ri --list` lists known classes.
+
+If a gem was installed with `--no-document`, generate its RI documentation with
+`gem rdoc GEM_NAME --ri`. Ruby core documentation depends on how your Ruby was
+installed; install the documentation package supplied by your Ruby manager or OS.
+
+### Read your project's documentation
+
+Save this small example as `greeter.rb`:
+
+```ruby
+class Greeter
+  # Returns a greeting for the given name.
+  #
+  #   Greeter.new.greet("Ruby") # => "Hello, Ruby!"
+  def greet(name)
+    "Hello, #{name}!"
+  end
+end
+```
+
+Generate its documentation and read the method:
+
+```sh
+rdoc --ri --quiet --op doc/ri greeter.rb
+rich-ri --no-standard-docs --doc-dir doc/ri --no-color --no-pager --width=60 Greeter#greet
+```
+
+The output below abbreviates the current directory as `.`:
+
+```text
+= Greeter#greet
+
+(from ./doc/ri)
+------------------------------------------------------------
+  greet(name)
+
+------------------------------------------------------------
+
+Returns a greeting for the given name.
+
+  Greeter.new.greet("Ruby") # => "Hello, Ruby!"
+```
+
+To use the same documentation sources for lookup and shell completion, configure
+`RI` in the current shell:
+
+| Shell | Command |
+| --- | --- |
+| Bash or Zsh | `export RI='--no-standard-docs --doc-dir doc/ri'` |
+| Fish | `set -gx RI '--no-standard-docs --doc-dir doc/ri'` |
+
+Only open RI stores you trust. RI caches use Ruby Marshal serialization; see
+[security policy](../SECURITY.md) for the trust boundary.
+
+## Manual
+
+`rich-ri --help` lists the options. `rich-ri --man` opens the full manual.
+To make the page available through `man rich-ri`, run `rich-ri --install-man`.
+The command prints its destination and any needed `MANPATH` setting. Repeat it
+when upgrading. Use `--install-man=DIR` to choose another `man1` directory.
+
+## Optional programs
+
+Ruby highlighting is built in. bat adds highlighting for shell commands and
+other tagged languages. less, or another RI-compatible pager, provides scrolling
+and search. `man` opens the bundled manual. These programs are available from
+your operating system's package manager.
+
+Without bat, those code blocks stay plain. If no pager is available, documentation
+is written to the terminal; `--no-pager` selects this behavior explicitly.
+`--help` and `--install-man` work without the `man` program.
+
+## Optional RDoc modes
+
+`rich-ri --server` starts RDoc's documentation web server on port 8214;
+`--server=PORT` selects another port. This mode requires the `webrick` gem:
+
+```sh
+gem install webrick
+```
+
+The server uses RDoc's web interface and network defaults, including listening
+on all interfaces. Stop it with Ctrl-C. rich-ri's terminal themes do not apply
+to the web pages.
+
+`--profile` runs Ruby's profiler while reading documentation and prints timing
+information when the command exits. It requires the `profile` gem:
+
+```sh
+gem install profile
+```
+
+Install either gem for the same Ruby that runs rich-ri. Neither is needed for
+normal terminal lookup, highlighting or completion. Missing optional gems produce
+an installation hint and exit status 1. When running through Bundler, add the
+needed gem to that bundle too.
+
+## Exit status
+
+The command exits with 0 on success, 1 for lookup or usage errors and 130 when
+interrupted. A closed output pipe is a normal exit.

data/exe/rich-ri

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rich_ri"
+
+exit RichRI::CLI.run(ARGV)

data/lib/rich_ri/ansi.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RichRI
+  SGR = /\e\[[\d;]*m/
+  RESET = "\e[0m"
+  COLORS = {
+    title: "1;36", heading: "1;34", subheading: "1;35",
+    code: "36", reference: "36", link: "4;36", label: "1;33",
+    muted: "90", emphasis: "3", bold: "1", strike: "9",
+    keyword: "35", string: "32", number: "33", constant: "33",
+    symbol: "33", method: "36", comment: "90", operator: "35"
+  }.freeze
+
+  def self.plain(text)
+    text.gsub(SGR, "")
+  end
+
+  # Documentation may contain literal terminal controls. Show them as text;
+  # only styles produced by this reader may reach the terminal as escapes.
+  def self.sanitize(text)
+    text.gsub(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\u0080-\u009f\u202a-\u202e\u2066-\u2069]|\r(?!\n)/) do |char|
+      format("\\u%04x", char.ord)
+    end
+  end
+
+  def self.width(text)
+    Reline::Unicode.calculate_width(text, true)
+  end
+
+  # Each word has balanced SGRs: less resets colors at newlines, and wrapping
+  # must never make a style bleed into the next paragraph or the shell prompt.
+  def self.paint(text, *roles, enabled: true)
+    Theme.new.paint(text, *roles, enabled:)
+  end
+end

data/lib/rich_ri/bat.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RichRI
+  # Optional highlighting must not prevent the reader from displaying a page.
+  class Bat
+    TIMEOUT = 2
+    MAX_INPUT = 1_048_576
+    MAX_OUTPUT = 8_388_608
+
+    def initialize(timeout: TIMEOUT, max_output: MAX_OUTPUT)
+      @timeout = timeout
+      @max_output = max_output
+      @available = true
+    end
+
+    def highlight(text, language:, theme:)
+      return unless @available && text.bytesize <= MAX_INPUT
+
+      output = capture(text, language, theme)
+      output&.force_encoding(text.encoding)
+      output = output.delete_suffix("\n") if output && !text.end_with?("\n") && output.end_with?("\n")
+      return output if output&.valid_encoding? && RichRI.plain(output) == text
+
+      @available = false
+      nil
+    rescue SystemCallError, IOError, Timeout::Error
+      @available = false
+      nil
+    end
+
+    private
+
+    def capture(text, language, theme)
+      args = ["bat", "--no-config", "--language=#{language}", "--style=plain", "--color=always",
+              "--paging=never", "--wrap=never", "--theme=#{theme}"]
+      Open3.popen2(*args, err: File::NULL, pgroup: true) do |input, output, waiter|
+        completed = false
+        writer = Thread.new { write(input, text) }
+        Timeout.timeout(@timeout) do
+          result = output.read(@max_output + 1).to_s
+          next if result.bytesize > @max_output
+
+          writer.value
+          status = waiter.value
+          completed = true
+          result if status.success?
+        end
+      ensure
+        writer&.kill
+        terminate(waiter) unless completed
+      end
+    end
+
+    def write(input, text)
+      input.write(text)
+    rescue Errno::EPIPE, IOError
+      nil
+    ensure
+      input.close unless input.closed?
+    end
+
+    def terminate(waiter)
+      Process.kill("TERM", -waiter.pid)
+      waiter.join(0.1)
+      # Descendants may still hold pipes open after their parent exits.
+      Process.kill("KILL", -waiter.pid)
+    rescue Errno::ESRCH
+      nil
+    ensure
+      waiter.join
+    end
+  end
+end