pty_compat 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ce2fec7856c5d46fb0b88e0f0ecc86828593ae8eb0ee1559c7778b35607902a1
+  data.tar.gz: 5dcaaf25e175c108f3fb04cf74a8b4ae0c03b898afea3dbb0b40be14547d4edc
+SHA512:
+  metadata.gz: f3411c48494e354226b1d8178e845d4912648648a03d5a54017583bbc9fb0adbbbf4c90d52d7a4ed70aa1b692e158621f0ac1529bd2a320e6e42dc870a4183a1
+  data.tar.gz: 1e9e6956e34c4cdba26db42f3e9e2d1499829a6fe3d3298c2e7cae3763915dd4c4667889b2f3e03c61abeacd1af25e37997a8f056a1143dd6a59691bf2d27034

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# [v0.0.1](https://github.com/Muriel-Salvan/pty_compat/compare/...v0.0.1) (2026-06-29 12:55:30)
+
+### Patches
+
+* [chore: lower minimum coverage threshold to 90%](https://github.com/Muriel-Salvan/pty_compat/commit/0adc20238ded82c8511a65f0e89ecab8482900e9)
+* [ci: add node-pty installation step in CI workflow](https://github.com/Muriel-Salvan/pty_compat/commit/c4e77e60e4a3be59f4034dbcf2a6a3fbb3ed6d4f)
+* [docs: update README with comprehensive documentation and Windows support](https://github.com/Muriel-Salvan/pty_compat/commit/b62cab654dd16a30233f89e75290f2a5b3f07d2b)
+* [feat: add SimpleCov for code coverage with 95% minimum threshold](https://github.com/Muriel-Salvan/pty_compat/commit/bfe51ddad41652f8501da02c075bd8f5a7f54bc6)
+* [docs: add YARD documentation infrastructure and enforce 100% documentation coverage](https://github.com/Muriel-Salvan/pty_compat/commit/586db5fdc71af12e0a4cbe9205ec2717476c790b)
+* [fix: set UTF-8 encoding on I/O streams and fix PTY.last_status + Added unit tests](https://github.com/Muriel-Salvan/pty_compat/commit/f8863af7a66660a01684f5e0f960208faed17503)
+* [feat: support environment variables and lazy process status in spawn](https://github.com/Muriel-Salvan/pty_compat/commit/1db60e395f8e915a40817ec8f8a8706fdcee168e)
+* [feat: expose last process status via `last_status` method](https://github.com/Muriel-Salvan/pty_compat/commit/1f3a56c3bcffd953e164ad73bfa9900c43f531f9)
+* [fix: resolve node-pty module path relative to project directory](https://github.com/Muriel-Salvan/pty_compat/commit/8d68466b5dc35ca671fb8458485b02066684a645)

data/README.md

@@ -0,0 +1,196 @@
+<div align="center">
+
+# pty_compat
+
+Make Ruby's `PTY` work on all platforms, including Windows
+
+[![License](https://img.shields.io/github/license/Muriel-Salvan/pty_compat?style=for-the-badge)](https://github.com/Muriel-Salvan/pty_compat/blob/main/LICENSE)
+[![Gem Version](https://img.shields.io/gem/v/pty_compat?style=for-the-badge)](https://rubygems.org/gems/pty_compat)
+[![CI](https://img.shields.io/github/actions/workflow/status/Muriel-Salvan/pty_compat/continuous_integration.yml?style=for-the-badge)](https://github.com/Muriel-Salvan/pty_compat/actions)
+[![Stars](https://img.shields.io/github/stars/Muriel-Salvan/pty_compat?style=for-the-badge)](https://github.com/Muriel-Salvan/pty_compat/stargazers)
+
+</div>
+
+## What is this?
+
+Ruby's built-in `PTY` module is not available on Windows. `pty_compat` transparently replaces it with an equivalent implementation using [`node-pty`](https://github.com/microsoft/node-pty), so your code works everywhere without changes.
+
+A single `require 'pty_compat'` patches `PTY.spawn` to fall back to a Node.js bridge when the native module is unavailable. No migration, no conditional logic, no platform checks.
+
+## Table of contents
+
+- [What is this?](#what-is-this)
+- [Quick Start](#quick-start)
+  - [Installation](#installation)
+  - [Usage](#usage)
+- [Requirements](#requirements)
+- [Features](#features)
+- [Public API](#public-api)
+- [Documentation](#documentation)
+- [How it works](#how-it-works)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Quick Start
+
+### Installation
+
+```sh
+bundle add pty_compat
+```
+
+If you're not using Bundler:
+
+```sh
+gem install pty_compat
+```
+
+On Windows, you also need `node-pty`:
+
+```sh
+npm install node-pty
+```
+
+> [!TIP]
+> If your project does not use Node.js, you can install `node-pty` locally. The bridge script resolves it from the current working directory.
+
+### Usage
+
+```ruby
+require 'pty_compat'
+
+# Non-block form
+reader, writer, pid = PTY.spawn('ping', '-c', '3', 'example.com')
+writer.puts('input')
+reader.each_line { |line| puts line }
+Process.wait(pid)
+
+# Block form
+PTY.spawn('ping', '-c', '3', 'example.com') do |reader, writer, pid|
+  writer.puts('input')
+  reader.each_line { |line| puts line }
+end
+
+# Retrieve the exit status portably
+status = PTY.last_status
+```
+
+## Requirements
+
+- Ruby >= 3.1
+- Node.js and `node-pty` (only required on platforms without native `PTY` support, typically Windows)
+
+## Features
+
+- **Zero-config drop-in.** A single `require` replaces `PTY.spawn` on Windows — no configuration, no platform checks, no conditional logic.
+- **Portable exit status.** Use `PTY.last_status` to retrieve the exit code on any platform instead of relying on `$?`.
+- **Non-block & block forms.** Supports both `PTY.spawn(command, args...) -> [reader, writer, pid]` and `PTY.spawn(command, args...) { |reader, writer, pid| ... }` forms.
+- **Windows support.** Leverages Microsoft's [`node-pty`](https://github.com/microsoft/node-pty) to provide a proper PTY on Windows, where Ruby's native `PTY` is unavailable.
+- **Lightweight.** The Ruby codebase is minimal, delegating the heavy lifting to a well-maintained native module.
+- **Works on all platforms.** Falls back to the `node-pty` bridge only when the native `PTY` module is unavailable; otherwise uses the standard library unchanged.
+
+## Public API
+
+### `PTY.spawn(command, *args) -> [reader, writer, pid]`
+
+Spawns a new process attached to a pseudo-terminal.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `command` | `String` | The command to execute (e.g. `'ping'`). |
+| `*args` | `String...` | Zero or more arguments passed to the command. |
+
+**Non-block form** returns a three-element array:
+
+| Element | Type | Description |
+|---------|------|-------------|
+| `reader` | `IO` | Readable IO (stdout + stderr merged). |
+| `writer` | `IO` | Writable IO (stdin of the spawned process). |
+| `pid` | `Integer` | Process ID of the spawned process. |
+
+### `PTY.spawn(command, *args) { |reader, writer, pid| block }`
+
+**Block form** yields `reader`, `writer`, and `pid` to the given block, and automatically closes the IOs after the block returns.
+
+### `PTY.last_status -> Process::Status | nil`
+
+Returns the exit status of the last spawned process.
+
+- On platforms with native `PTY`, mirrors `$?`.
+- On the fallback path, returns a `Process::Status` constructed from the exit code captured by the `node-pty` bridge.
+- Returns `nil` if no process has been spawned yet or if the last spawn failed.
+
+> [!TIP]
+> Prefer `PTY.last_status` over `$?` for portable code that runs on both Windows and Unix.
+
+## Documentation
+
+- [RubyDoc](https://www.rubydoc.info/gems/pty_compat)
+
+## How it works
+
+1. `pty_compat` tries to load Ruby's standard `PTY` library first.
+2. On `LoadError` (as raised on Windows), it prepends `PtyCompat::NodePty` into `PTY`.
+3. `PtyCompat::NodePty` implements `PTY.spawn` through a Node.js bridge that uses `node-pty` to create a pseudo-terminal.
+4. Stdout and stderr are merged into a single readable IO, matching the behaviour of Ruby's native `PTY.spawn`.
+
+```
+┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
+│  Ruby code   │────▶│  PTY.spawn(...)  │────▶│  node-pty    │
+│  (your app)  │     │  (patched)       │     │  bridge.js   │
+└──────────────┘     └──────────────────┘     └──────┬───────┘
+                                                     │
+                                                     ▼
+                                              ┌──────────────┐
+                                              │  Command     │
+                                              │  (shell,     │
+                                              │   process)   │
+                                              └──────────────┘
+```
+
+### `PTY.last_status`
+
+On platforms with native `PTY`, `PTY.last_status` returns `$?` (`Process::Status`). On the fallback path, the bridge captures the exit code and exposes it through the same method. Prefer this over `$?` for portable code.
+
+### Why not a pure Ruby PTY?
+
+Alternative approaches rely on platform-specific C extensions that are painful to compile on Windows, or expose an incomplete `PTY` interface. `pty_compat` delegates the heavy lifting to [`node-pty`](https://github.com/microsoft/node-pty), a well-maintained native module by Microsoft that supports Windows, macOS, and Linux. This keeps the Ruby code small and the platform coverage broad.
+
+## Development
+
+```sh
+bundle install
+```
+
+Run the tests:
+
+```sh
+bundle exec rspec
+```
+
+Lint with RuboCop:
+
+```sh
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [Muriel-Salvan/pty_compat](https://github.com/Muriel-Salvan/pty_compat).
+
+<a href="https://github.com/Muriel-Salvan/pty_compat/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Muriel-Salvan/pty_compat" />
+</a>
+
+## License
+
+The gem is available as open source under the terms of the [BSD-3-Clause License](LICENSE).
+
+---
+
+<div align="center">
+
+[![Star History Chart](https://api.star-history.com/svg?repos=Muriel-Salvan/pty_compat&type=Date)](https://star-history.com/#Muriel-Salvan/pty_compat&Date)
+
+</div>

data/lib/pty_compat/assets/node_pty_bridge.js

@@ -0,0 +1,38 @@
+// This NodeJS bridge is used only on platforms that don't support Ruby's PTY standard library.
+// This is needed to use the CLIs from Ruby on Windows.
+// This bridge will use the node-pty module of NodeJS to bridge a command line through a PTY interface.
+// To use it the user must first install the node-pty module in the project that will be using the pty_compat Rubygem, like this:
+// npm install node-pty
+
+const pty = require(
+  require.resolve("node-pty", {
+    paths: [process.cwd()]
+  })
+);
+
+const [cmd, ...args] = process.argv.slice(2);
+
+const shell = pty.spawn(cmd, args, {
+  name: "xterm-color",
+  cols: 80,
+  rows: 30,
+  cwd: process.cwd(),
+  env: process.env
+});
+
+// Send output to Ruby
+shell.on("data", (data) => {
+  process.stdout.write(data);
+});
+
+// Read commands from Ruby (stdin)
+process.stdin.setEncoding("utf8");
+
+process.stdin.on("data", (data) => {
+  shell.write(data);
+});
+
+// Catch the exit properly
+shell.on("exit", (code, signal) => {
+  process.exit(code ?? 0);
+});

data/lib/pty_compat/node_pty.rb

@@ -0,0 +1,95 @@
+require 'open3'
+
+module PtyCompat
+  # Provide a similar interface as the PTY one that could work on platforms that don't support PTY (for example Windows).
+  # Internally uses NodeJS's node-pty.
+  module NodePty
+    # @!group Public API
+
+    # Spawn a command in a PTY and return or yield its outputs, input and pid
+    #
+    # @param args [Array] The command arguments to execute (see [`::PTY#spawn`](https://www.rubydoc.info/stdlib/pty/PTY%2Espawn))
+    # @yield An optional code called with all PTY outputs, input and PID.
+    # @yieldparam r [IO] The reader output (containing stdout and stderr).
+    # @yieldparam w [IO] The writer input (containing stdin).
+    # @yieldparam pid [Integer] The process PID.
+    # @return [Array<IO, Integer>, nil] The reader, writer and PID of the process, or nil if used with a yielded block.
+    #   - r [IO] The reader output (containing stdout and stderr).
+    #   - w [IO] The writer input (containing stdin).
+    #   - pid [Integer] The process PID.
+    def spawn(*args)
+      env, cmd = args.first.is_a?(Hash) ? [[args.first], args[1..]] : [[], args]
+      node_args = env + ['node', "#{__dir__}/assets/node_pty_bridge.js"] + cmd
+      if block_given?
+        Open3.popen3(*node_args) do |stdin, stdout, stderr, wait_thr|
+          @last_wait_thr = wait_thr
+          yield popen3_to_pty(stdin, stdout, stderr, wait_thr)
+        end
+      else
+        stdin, stdout, stderr, wait_thr = Open3.popen3(*node_args)
+        @last_wait_thr = wait_thr
+        popen3_to_pty(stdin, stdout, stderr, wait_thr)
+      end
+    end
+
+    # @return [Process::Status] Last process status
+    def last_status
+      @last_wait_thr.value
+    end
+
+    private
+
+    # Convert the popen3 descriptors to PTY ones
+    #
+    # @param stdin [IO] The stdin descriptor
+    # @param stdout [IO] The stdout descriptor
+    # @param stderr [IO] The stderr descriptor
+    # @param wait_thread [Process::Waiter] The process information
+    # @return [Array<IO, Integer>] The corresponding PTY reader, writer and PID.
+    #   - r [IO] The reader output (containing stdout and stderr).
+    #   - w [IO] The writer input (containing stdin).
+    #   - pid [Integer] The process PID.
+    def popen3_to_pty(stdin, stdout, stderr, wait_thread)
+      stdout.set_encoding(Encoding::UTF_8)
+      stderr.set_encoding(Encoding::UTF_8)
+      stdin.set_encoding(Encoding::UTF_8)
+      # Create a pipe to combine stdout and stderr into a single IO
+      combined_r, combined_w = IO.pipe
+      # Reader thread for stdout
+      stdout_reader = Thread.new do
+        IO.copy_stream(stdout, combined_w)
+      rescue IOError
+        # Ignore errors from closed pipe
+      ensure
+        begin
+          stdout.close
+        rescue RuntimeError
+          nil
+        end
+      end
+      # Reader thread for stderr
+      stderr_reader = Thread.new do
+        IO.copy_stream(stderr, combined_w)
+      rescue IOError
+        # Ignore errors from closed pipe
+      ensure
+        begin
+          stderr.close
+        rescue RuntimeError
+          nil
+        end
+      end
+      # Closer thread: close the write end of the combined pipe once both stdout and stderr have finished being read.
+      Thread.new do
+        stdout_reader.join
+        stderr_reader.join
+        begin
+          combined_w.close
+        rescue RuntimeError
+          nil
+        end
+      end
+      [combined_r, stdin, wait_thread.pid]
+    end
+  end
+end

data/lib/pty_compat/patches/pty.rb

@@ -0,0 +1,26 @@
+require 'English'
+
+# Augment PTY module with last_status
+module PTY
+  # @!group Public API
+
+  # @return [Process::Status] Last process status.
+  #   Use this instead of $? as some workaround methods don't set $? properly and we can't modify this variable.
+  def self.last_status
+    # Default implementation
+    $CHILD_STATUS
+  end
+end
+
+begin
+  require 'pty'
+rescue LoadError => e
+  if e.message == 'cannot load such file -- pty'
+    module PTY
+      class << self
+        # Fallback on node-pty
+        prepend PtyCompat::NodePty
+      end
+    end
+  end
+end

data/lib/pty_compat/version.rb

@@ -0,0 +1,6 @@
+module PtyCompat
+  # @!group Public API
+
+  # Gem version
+  VERSION = '1.0.0'
+end

data/lib/pty_compat.rb

@@ -0,0 +1,10 @@
+require 'zeitwerk'
+
+Zeitwerk::Loader.for_gem.setup
+
+# Provide ways to implement Ruby's PTY's interface on all platofrms.
+module PtyCompat
+end
+
+# Make sure PTY is loaded with eventual fallbacks.
+require 'pty_compat/patches/pty'

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: pty_compat
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Muriel Salvan
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+email: muriel@x-aeon.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- TODO.md
+- lib/pty_compat.rb
+- lib/pty_compat/assets/node_pty_bridge.js
+- lib/pty_compat/node_pty.rb
+- lib/pty_compat/patches/pty.rb
+- lib/pty_compat/version.rb
+homepage: https://github.com/Muriel-Salvan/pty_compat
+licenses:
+- BSD-3-Clause
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Make Ruby's PTY work on all platforms
+test_files: []