rails_server_hotkeys 1.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dcf7eece0e781456e10984440dacaa89d63f1c8a2d5e253b3e46edbb8777bd36
+  data.tar.gz: 25f0dc57f124910142dfef2d37789e772faf26b04ea00c564bb3adfaa2e84072
+SHA512:
+  metadata.gz: bbd24268025046933f74dc66a92a6359c79253cb39b33dbf3eac561ec91619c0b5931fe90e36a17f11a9d393313610395a33b30af37600101ec5cfd88680ddf4
+  data.tar.gz: 8c259bab6875bdbeb776e5ee0e5ec89c46abd65ca6843d4bbeece9c4513cba5687e00bfec2d55451b78b9af90728f158f0b756f01c492467ecba2845090e9163

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.1.1] - 2026-10-31
+
+### Changed
+- Gem metadata: source code, changelog and bug tracker links; MFA required to publish.
+- `CHANGELOG.md` is now included in the gem package.
+
+## [1.1.0] - 2026-10-31
+
+### Added
+- Hotkeys for `rails server`: `r` restart, `c` clear, `o` open browser, `h`/`?` help, `q` quit.
+- `RailsServerHotkeys.register` / `unregister` for custom hotkeys.
+- `RailsServerHotkeys.color` to customize message color (ANSI name, 0-255, hex or `nil`); honors `NO_COLOR`.
+- `config.hotkeys.enabled`, `config.hotkeys.url` and `RAILS_SERVER_HOTKEYS=false` to configure or disable.
+- `o` opens the port the server is actually listening on.
+- Banner shown after Puma's "Use Ctrl-C to stop".
+
+[Unreleased]: https://github.com/samuelpismel/rails_server_hotkeys/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/samuelpismel/rails_server_hotkeys/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/samuelpismel/rails_server_hotkeys/releases/tag/v1.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samuel Gavassi Pismel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,122 @@
+# rails_server_hotkeys
+
+Expo-style keyboard shortcuts for `bin/rails server`. Press `r` to restart the server — no more `touch tmp/restart.txt` in another terminal.
+
+```
+=> Booting Puma
+...
+› Press r to restart, h for help
+```
+
+## Install
+
+```ruby
+# Gemfile
+gem "rails_server_hotkeys", group: :development
+```
+
+That's it. Run `bin/rails s` and press a key.
+
+| Key | Action |
+|---|---|
+| `r` | restart the server (same as `bin/rails restart`) |
+| `c` | clear the terminal |
+| `o` | open the app in the browser |
+| `h` / `?` | list hotkeys |
+| `q` | quit the server |
+
+## Custom hotkeys
+
+```ruby
+# config/initializers/hotkeys.rb
+if defined?(RailsServerHotkeys)
+  RailsServerHotkeys.register("m", "run db:migrations") { system("bin/rails db:migrate") }
+  RailsServerHotkeys.register("t", "run custom task") { system("bin/rails myapp:do_something") }
+  RailsServerHotkeys.register("e", "run system echo") { system("echo 'custom message'") }
+end
+```
+
+Registering an existing key replaces it; `RailsServerHotkeys.unregister("o")` removes one.
+
+## Configuration
+
+```ruby
+# config/environments/development.rb
+config.hotkeys.enabled = false               # turn it off
+config.hotkeys.url = "https://myapp.test"    # URL opened by `o` (default: localhost on the port the server is listening on)
+```
+
+Or disable for a single run: `RAILS_SERVER_HOTKEYS=false bin/rails s`.
+
+### Color
+
+Messages are light blue by default. Change it in an initializer:
+
+```ruby
+# config/initializers/hotkeys.rb
+if defined?(RailsServerHotkeys)
+  RailsServerHotkeys.color = :green       # black, red, green, yellow, blue, magenta, cyan, white,
+                                          # or light_* of any of them (the default is :green)
+  RailsServerHotkeys.color = 208          # 256-color palette (0-255)
+  RailsServerHotkeys.color = "#ff8800"    # true color (hex)
+  RailsServerHotkeys.color = nil          # no color
+end
+```
+
+An invalid value raises `ArgumentError` at boot. Colors are skipped when the output isn't a terminal or `NO_COLOR` is set.
+
+## When is it active?
+
+Only for `rails server`, in the `development` environment, when stdin is a terminal. Console, rake, tests, jobs and non-interactive runs (Docker without `-it`, CI) are untouched.
+
+## Caveats
+
+- **Restart needs Puma's `tmp_restart` plugin.** It's in the `config/puma.rb` generated by Rails; if yours lacks it, add `plugin :tmp_restart`.
+- **`bin/dev` (foreman) doesn't forward stdin**, so hotkeys can't work there. Run `bin/rails s` directly, or use overmind and `overmind connect web`.
+- **Unix/macOS only** (uses `stty`). On Windows the gem does nothing.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+### Trying it in a dummy app
+
+The unit tests run without Rails, but hotkeys only show up for real under `rails server` in a terminal. To try your changes by hand, create a throwaway app next to the gem:
+
+```sh
+# Needs the rails and bundler gems (`gem install rails bundler`)
+cd ..
+rails new hotkeys-dummy --minimal --skip-git
+cd hotkeys-dummy
+
+# Point the app at your local copy of the gem
+echo 'gem "rails_hotkeys", path: "../restart-rails-hotkeys", group: :development' >> Gemfile
+bundle install
+
+bin/rails s
+```
+
+Adjust the `path:` if your clone has a different folder name.
+
+You should see this in light blue, right after Puma's `Use Ctrl-C to stop`:
+
+```
+› Press r to restart, h for help
+```
+
+Things to check:
+
+- `r` prints `* Restarting...` and the server comes back up
+- `h` lists the hotkeys, `c` clears the screen
+- `o` opens the browser on the port the server is listening on (try `bin/rails s -p 4000`)
+- `q` or Ctrl+C stops the server, and your shell echoes what you type again
+- `bin/rails s < /dev/null` boots normally with no banner (no TTY, hotkeys off)
+
+Because the gem is loaded through `path:`, edits to it take effect on the next restart: press `r` instead of stopping the server. You don't need to run `bundle install` again unless you change the gemspec.
+
+## License
+
+MIT

data/lib/rails_server_hotkeys/actions.rb

@@ -0,0 +1,94 @@
+require "fileutils"
+require "rbconfig"
+require "socket"
+
+module RailsServerHotkeys
+  # Built-in hotkeys. They resolve paths and URLs when pressed, so they work no
+  # matter when the app finishes booting.
+  module Actions
+    class << self
+      attr_writer :root, :url, :output
+
+      def root
+        @root || (defined?(Rails) && Rails.respond_to?(:root) && Rails.root) || Dir.pwd
+      end
+
+      def url
+        @url || "http://localhost:#{listening_ports.first || ENV.fetch("PORT", 3000)}"
+      end
+
+      # Ports this process is actually listening on, however they were chosen
+      # (-p, PORT, config/puma.rb). Resolved on demand, so restarts are covered.
+      def listening_ports
+        ObjectSpace.each_object(TCPServer).filter_map do |server|
+          next if server.closed?
+
+          server.local_address.ip_port
+        rescue IOError, SystemCallError
+          nil
+        end.uniq.sort
+      end
+
+      def output
+        @output || $stdout
+      end
+
+      def banner
+        colorize("\n› Press r to restart, h for help")
+      end
+
+      # Uses RailsServerHotkeys.color, only on a real terminal (and respecting NO_COLOR).
+      def colorize(text)
+        code = Color.sgr(RailsServerHotkeys.color)
+        return text if code.nil? || ENV["NO_COLOR"] || !(output.respond_to?(:tty?) && output.tty?)
+
+        "\e[#{code}m#{text}\e[0m"
+      end
+
+      # Same as `bin/rails restart`; picked up by Puma's tmp_restart plugin.
+      def restart
+        path = File.join(root.to_s, "tmp", "restart.txt")
+        FileUtils.mkdir_p(File.dirname(path))
+        FileUtils.touch(path)
+        output.puts colorize("› Restarting...")
+      end
+
+      def clear
+        output.print "\e[H\e[2J\e[3J"
+        output.puts banner
+      end
+
+      def open_browser
+        command = case RbConfig::CONFIG["host_os"]
+                  when /darwin/ then "open"
+                  else "xdg-open"
+                  end
+        output.puts colorize("› Opening #{url}")
+        pid = Process.spawn(command, url, out: File::NULL, err: File::NULL)
+        Process.detach(pid)
+      end
+
+      def help
+        output.puts colorize("› Hotkeys:")
+        RailsServerHotkeys.hotkeys.each_value do |hotkey|
+          output.puts colorize("    #{hotkey.key}  #{hotkey.description}")
+        end
+      end
+
+      def quit
+        Process.kill(:INT, Process.pid)
+      end
+
+      def register_defaults
+        RailsServerHotkeys.register("r", "restart the server") { restart }
+        RailsServerHotkeys.register("c", "clear the terminal") { clear }
+        RailsServerHotkeys.register("o", "open the app in the browser") { open_browser }
+        RailsServerHotkeys.register("h", "show this help") { help }
+        RailsServerHotkeys.register("?", "show this help") { help }
+        RailsServerHotkeys.register("q", "quit the server") { quit }
+      end
+    end
+  end
+end
+
+RailsServerHotkeys::Actions.register_defaults

data/lib/rails_server_hotkeys/boot_hook.rb

@@ -0,0 +1,28 @@
+module RailsServerHotkeys
+  # Runs a block once the server has booted, so output lands after Puma's
+  # "Use Ctrl-C to stop" instead of in the middle of its startup log.
+  module BootHook
+    # Puma >= 6.5 renamed fire_on_booted! to fire_after_booted!.
+    PUMA_EVENTS = %i[fire_after_booted! fire_on_booted!].freeze
+
+    def self.call(&block)
+      load_puma_events
+      event = defined?(Puma::Events) && PUMA_EVENTS.find { |name| Puma::Events.method_defined?(name) }
+      return block.call unless event
+
+      Puma::Events.prepend(Module.new do
+        define_method(event) do |*args, **kwargs|
+          super(*args, **kwargs).tap { block.call }
+        end
+      end)
+    end
+
+    # When Rails runs server blocks, the Puma handler is chosen but
+    # Puma::Events isn't required yet.
+    def self.load_puma_events
+      require "puma/events" if defined?(Puma) && !defined?(Puma::Events)
+    rescue LoadError
+      nil
+    end
+  end
+end

data/lib/rails_server_hotkeys/color.rb

@@ -0,0 +1,29 @@
+module RailsServerHotkeys
+  # Turns a user-facing color setting into an ANSI SGR code.
+  module Color
+    NAMES = %i[black red green yellow blue magenta cyan white].freeze
+
+    CODES = NAMES.each_with_index.each_with_object({}) do |(name, index), codes|
+      codes[name] = (30 + index).to_s
+      codes[:"light_#{name}"] = (90 + index).to_s
+    end.freeze
+
+    HEX = /\A#?(\h{2})(\h{2})(\h{2})\z/
+
+    # :green / "light_green" => named color, 0..255 => 256-color palette,
+    # "#ff8800" => true color, nil / false => no color.
+    def self.sgr(color)
+      case color
+      when nil, false then nil
+      when Integer
+        "38;5;#{color}" if color.between?(0, 255)
+      when Symbol, String
+        CODES[color.to_sym] || (match = HEX.match(color.to_s)) && "38;2;#{match.captures.map(&:hex).join(";")}"
+      end
+    end
+
+    def self.valid?(color)
+      color.nil? || color == false || !sgr(color).nil?
+    end
+  end
+end

data/lib/rails_server_hotkeys/listener.rb

@@ -0,0 +1,34 @@
+module RailsServerHotkeys
+  # Reads keys from +input+ and runs the matching hotkey. Unknown keys are ignored.
+  class Listener
+    def initialize(input:, output:, hotkeys:)
+      @input = input
+      @output = output
+      @hotkeys = hotkeys
+    end
+
+    def start
+      @thread = Thread.new { run }
+      @thread.name = "rails_server_hotkeys"
+      @thread.report_on_exception = false
+      @thread
+    end
+
+    def run
+      while (char = @input.getc)
+        handle(char)
+      end
+    rescue IOError, SystemCallError
+      # stdin closed; nothing left to listen to
+    end
+
+    def handle(char)
+      hotkey = @hotkeys[char] || @hotkeys[char.downcase]
+      return unless hotkey
+
+      hotkey.action.call
+    rescue StandardError => e
+      @output.puts "[rails_server_hotkeys] '#{char}' failed: #{e.class}: #{e.message}"
+    end
+  end
+end

data/lib/rails_server_hotkeys/railtie.rb

@@ -0,0 +1,18 @@
+require "rails/railtie"
+
+module RailsServerHotkeys
+  class Railtie < Rails::Railtie
+    config.hotkeys = ActiveSupport::OrderedOptions.new
+    config.hotkeys.enabled = true
+    config.hotkeys.url = nil
+
+    # Runs only for `rails server`; never for console, rake, tests or jobs.
+    server do
+      options = Rails.application.config.hotkeys
+      next unless RailsServerHotkeys.enabled?(rails_env: Rails.env, config_enabled: options.enabled)
+
+      RailsServerHotkeys::Actions.url = options.url if options.url
+      RailsServerHotkeys.start
+    end
+  end
+end

data/lib/rails_server_hotkeys/terminal.rb

@@ -0,0 +1,52 @@
+module RailsServerHotkeys
+  # Puts the TTY in "cbreak" mode: keys are delivered one at a time and not
+  # echoed, while output processing (OPOST) and signals (ISIG, so Ctrl+C) stay
+  # untouched. IO#raw would disable OPOST and make the server logs staircase.
+  class Terminal
+    # Puma restarts by exec'ing a new process, which skips at_exit. Give the
+    # terminal back right before any exec so the new process sees (and saves)
+    # the user's original settings.
+    module RestoreBeforeExec
+      def exec(*args)
+        RailsServerHotkeys::Terminal.current&.restore!
+        super
+      end
+    end
+
+    class << self
+      attr_accessor :current
+    end
+
+    def initialize(input)
+      @input = input
+    end
+
+    def enable!
+      @state = stty_state
+      return unless @state && stty("-icanon", "-echo", "min", "1")
+
+      self.class.current = self
+      Kernel.singleton_class.prepend(RestoreBeforeExec)
+      Process.singleton_class.prepend(RestoreBeforeExec)
+      at_exit { restore! }
+    end
+
+    def restore!
+      stty(@state) if @state
+      @state = nil
+    end
+
+    private
+
+    def stty_state
+      state = IO.popen(%w[stty -g], in: @input, err: File::NULL, &:read).strip
+      state.empty? ? nil : state
+    rescue SystemCallError
+      nil
+    end
+
+    def stty(*args)
+      system("stty", *args, in: @input, err: File::NULL)
+    end
+  end
+end

data/lib/rails_server_hotkeys/version.rb

@@ -0,0 +1,3 @@
+module RailsServerHotkeys
+  VERSION = "1.1.1"
+end

data/lib/rails_server_hotkeys.rb

@@ -0,0 +1,76 @@
+require "rails_server_hotkeys/version"
+require "rails_server_hotkeys/terminal"
+require "rails_server_hotkeys/listener"
+require "rails_server_hotkeys/boot_hook"
+require "rails_server_hotkeys/color"
+
+module RailsServerHotkeys
+  Hotkey = Struct.new(:key, :description, :action)
+  DEFAULT_COLOR = :green
+
+  class << self
+    # Registers a hotkey. Registering an existing key replaces it.
+    #
+    #   RailsServerHotkeys.register("m", "Run migrations") { system("bin/rails db:migrate") }
+    def register(key, description, &action)
+      raise ArgumentError, "hotkey must be a single character" unless key.is_a?(String) && key.length == 1
+      raise ArgumentError, "a block is required" unless action
+
+      hotkeys[key] = Hotkey.new(key, description, action)
+    end
+
+    def unregister(key)
+      hotkeys.delete(key)
+    end
+
+    def hotkeys
+      @hotkeys ||= {}
+    end
+
+    # Color of the gem's messages.
+    #
+    #   RailsServerHotkeys.color = :green      # any of Color::CODES
+    #   RailsServerHotkeys.color = 208         # 256-color palette
+    #   RailsServerHotkeys.color = "#ff8800"   # true color
+    #   RailsServerHotkeys.color = nil         # no color
+    def color
+      defined?(@color) ? @color : DEFAULT_COLOR
+    end
+
+    def color=(value)
+      unless Color.valid?(value)
+        raise ArgumentError, "invalid color #{value.inspect}; use one of #{Color::CODES.keys.join(", ")}, " \
+                             "an integer 0-255, a hex string like \"#ff8800\", or nil"
+      end
+
+      @color = value
+    end
+
+    def reset_color
+      remove_instance_variable(:@color) if defined?(@color)
+    end
+
+    # Whether hotkeys should run for this process.
+    def enabled?(input: $stdin, env: ENV, rails_env: nil, config_enabled: true)
+      return false unless config_enabled
+      return false if %w[0 false off].include?(env["RAILS_SERVER_HOTKEYS"].to_s.downcase)
+      return false if Gem.win_platform?
+      return false if rails_env && rails_env != "development"
+
+      input.respond_to?(:tty?) && input.tty?
+    end
+
+    def start(input: $stdin, output: $stdout)
+      return if @listener
+
+      Terminal.new(input).enable!
+      @listener = Listener.new(input: input, output: output, hotkeys: hotkeys)
+      @listener.start
+      BootHook.call { output.puts Actions.banner }
+      @listener
+    end
+  end
+end
+
+require "rails_server_hotkeys/actions"
+require "rails_server_hotkeys/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: rails_server_hotkeys
+version: !ruby/object:Gem::Version
+  version: 1.1.1
+platform: ruby
+authors:
+- Samuel Gavassi Pismel
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: 'Adds interactive hotkeys to the Rails development server: r to restart,
+  c to clear, o to open the browser, q to quit, and your own.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/rails_server_hotkeys.rb
+- lib/rails_server_hotkeys/actions.rb
+- lib/rails_server_hotkeys/boot_hook.rb
+- lib/rails_server_hotkeys/color.rb
+- lib/rails_server_hotkeys/listener.rb
+- lib/rails_server_hotkeys/railtie.rb
+- lib/rails_server_hotkeys/terminal.rb
+- lib/rails_server_hotkeys/version.rb
+homepage: https://github.com/samuelpismel/rails_server_hotkeys
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/samuelpismel/rails_server_hotkeys
+  source_code_uri: https://github.com/samuelpismel/rails_server_hotkeys
+  changelog_uri: https://github.com/samuelpismel/rails_server_hotkeys/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/samuelpismel/rails_server_hotkeys/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.7
+specification_version: 4
+summary: Keyboard hotkeys for `rails server` (press r to restart).
+test_files: []