rbwatch 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ff7a8e55dbe3107b8476b224e28e0da6a2d13caceded52652a23449c95878db
+  data.tar.gz: 5f956a57c909f30f0625dd80e4765988b11abb3377b6d15526daf51662356840
+SHA512:
+  metadata.gz: 153366c2a7cda009abec391429663ceddd20745003198c063f354189189a5f7ca794a6bde5285994bbd095abb53853796f24dc7c1c86d44c234138faf8b946fe
+  data.tar.gz: 78d5d5eb3edf0d759b840b228795cb6134ab8f03bd9223ecd2c224a98d701fbb9a9dc0730cc7a24b65c92e1d1a4b8d99eeb7cc47a54e0f07794dc027fcb40640

data/README.md

@@ -0,0 +1,217 @@
+# RBWatch
+
+RBWatch is a Ruby process watcher inspired by nodemon.
+
+It watches source files recursively and restarts the process automatically when changes are detected.
+
+## Goals
+
+- Clean architecture
+- Delightful terminal output
+- Reliable process lifecycle management
+- Works on Linux, macOS, and WSL
+
+## Installation
+
+```bash
+bundle install
+```
+
+If you install RBWatch globally with RubyGems, the `rbwatch` and `rbw` executables are available directly on your shell `PATH`:
+
+```bash
+gem install rbwatch
+```
+
+If you want to use RBWatch from another project while developing locally, add it to that project's `Gemfile`:
+
+```ruby
+gem "rbwatch", path: "../../../open-source/rbwatch"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### From this repository checkout
+
+Run a Ruby app directly:
+
+```bash
+rbwatch app.rb
+```
+
+If you are working from this repository checkout:
+
+```bash
+bundle exec exe/rbwatch app.rb
+```
+
+Or use the alias:
+
+```bash
+rbw app.rb
+```
+
+If you are running from this repository checkout, use:
+
+```bash
+bundle exec exe/rbw app.rb
+```
+
+### From another project
+
+If RBWatch is added to another project's `Gemfile`, run it through Bundler:
+
+```bash
+bundle exec rbwatch app.rb
+bundle exec rbw app.rb
+```
+
+Bundler makes the executables available to the bundle, but it does not place them on your shell `PATH`.
+
+If you want a direct command without `bundle exec`, generate binstubs in that project:
+
+```bash
+bundle binstubs rbwatch
+bin/rbw app.rb
+```
+
+If the first argument is a Ruby file, RBWatch expands it to `ruby app.rb` automatically.
+
+You can still run explicit commands:
+
+```bash
+bundle exec exe/rbwatch ruby app.rb
+```
+
+Or watch a Bundler-driven command:
+
+```bash
+bundle exec exe/rbwatch bundle exec ruby app.rb
+```
+
+Useful flags:
+
+```bash
+bundle exec exe/rbwatch --delay 500 ruby app.rb
+bundle exec exe/rbwatch --ext rb,erb,yml ruby app.rb
+bundle exec exe/rbwatch --ignore tmp,log,node_modules ruby app.rb
+bundle exec exe/rbwatch --clear ruby app.rb
+bundle exec exe/rbwatch --no-clear ruby app.rb
+bundle exec exe/rbwatch --verbose ruby app.rb
+bundle exec exe/rbwatch --no-banner ruby app.rb
+bundle exec exe/rbwatch --no-color ruby app.rb
+bundle exec exe/rbwatch --theme neon ruby app.rb
+bundle exec exe/rbwatch --watch app,config ruby app.rb
+bundle exec exe/rbwatch --config rbwatch.yml ruby app.rb
+```
+
+## Configuration File
+
+RBWatch can load a YAML configuration file with `--config` or automatically discover `rbwatch.yml`, `rbwatch.yaml`, `.rbwatch.yml`, or `.rbwatch.yaml` in the current directory.
+
+Example `rbwatch.yml`:
+
+```yaml
+delay: 300
+extensions:
+  - rb
+  - erb
+  - yml
+ignore:
+  - tmp
+  - log
+watch_paths:
+  - app
+  - config
+command: ruby app.rb
+clear: true
+verbose: true
+banner: true
+color: true
+theme: neon
+```
+
+CLI options always win over values from the config file.
+
+## Defaults
+
+RBWatch watches these extensions by default:
+
+- `rb`
+- `erb`
+- `haml`
+- `slim`
+- `rake`
+- `yml`
+- `yaml`
+- `json`
+
+Ignored paths by default:
+
+- `log`
+- `tmp`
+- `.git`
+- `node_modules`
+
+Default debounce delay: `300ms`
+
+By default, RBWatch clears the visible terminal and scrollback before each restart when it is attached to a TTY. Use `--no-clear` or `clear: false` if you want to keep previous output on screen.
+
+The startup dashboard shows the command, watched roots, theme, and config file when available.
+
+If you pass `--stats`, the status card also shows restart count and uptime.
+
+## Architecture
+
+```text
+rbwatch/
+├── bin/
+│   ├── rbwatch
+│   └── rbw
+├── exe/
+│   ├── rbwatch
+│   └── rbw
+├── lib/
+│   └── rbwatch/
+│       ├── cli.rb
+│       ├── configuration.rb
+│       ├── dashboard.rb
+│       ├── file_scanner.rb
+│       ├── process_manager.rb
+│       ├── runner.rb
+│       ├── theme.rb
+│       ├── watcher.rb
+│       ├── version.rb
+│       └── rbwatch.rb
+└── spec/
+```
+
+## Notes
+
+- Process spawning uses `spawn`.
+- Restarting uses `Process.kill("TERM", pid)` first and escalates if the process refuses to exit.
+- CTRL+C and `TERM` are handled gracefully.
+- The UI uses TTY gems for boxed layouts, cursors, spinners, tables, and screen sizing.
+- Fast startup failures do not restart in a tight loop; RBWatch waits for file changes before trying again.
+
+## Future-ready hooks
+
+The configuration layer already leaves room for:
+
+- `--exec`
+- `--config rbwatch.yml`
+- `--watch app,config`
+- `--sound`
+- `--desktop-notify`
+- `--history`
+- `--theme neon`
+- `--theme minimal`
+- `--theme retro`
+- `--theme ruby`
+- `--theme matrix`

data/bin/rbw

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/rbwatch"
+
+exit RBWatch::CLI.start(ARGV)
+

data/bin/rbwatch

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/rbwatch"
+
+exit RBWatch::CLI.start(ARGV)
+

data/exe/rbw

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+load File.expand_path("../bin/rbw", __dir__)
+

data/exe/rbwatch

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+load File.expand_path("../bin/rbwatch", __dir__)
+

data/lib/rbwatch/cli.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module RBWatch
+  class CLI
+    def self.start(argv = ARGV, stdout: $stdout, stderr: $stderr, stdin: $stdin)
+      new(argv, stdout: stdout, stderr: stderr, stdin: stdin).run
+    end
+
+    def initialize(argv, stdout:, stderr:, stdin:)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @stdin = stdin
+    end
+
+    def run
+      configuration = parse
+      if configuration == :help
+        @stdout.puts parser if @show_help
+        return 0
+      end
+
+      Runner.new(configuration: configuration).run
+    rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+      @stderr.puts e.message
+      @stderr.puts
+      @stderr.puts parser
+      1
+    rescue Theme::UnknownThemeError => e
+      @stderr.puts e.message
+      1
+    rescue ArgumentError => e
+      @stderr.puts e.message
+      @stderr.puts
+      @stderr.puts parser
+      1
+    end
+
+    def parse
+      options = default_options
+      parser = build_parser(options)
+      parser.parse!(@argv)
+
+      if options.delete(:help_requested)
+        @show_help = true
+        return :help
+      end
+
+      configuration = Configuration.from_sources(
+        cli_options: options,
+        command: @argv,
+        stdin: @stdin,
+        stdout: @stdout,
+        stderr: @stderr
+      )
+
+      if configuration.command.empty?
+        @stderr.puts parser
+        @show_help = false
+        return :help
+      end
+
+      configuration
+    ensure
+      @parser = parser
+    end
+
+    def parser
+      @parser || build_parser(default_options)
+    end
+
+    private
+
+    def default_options
+      {
+        delay: nil,
+        extensions: nil,
+        ignore: nil,
+        watch_paths: nil,
+        clear: nil,
+        verbose: nil,
+        banner: nil,
+        color: nil,
+        theme_name: nil,
+        restart_on_exit: nil,
+        sound: nil,
+        desktop_notify: nil,
+        stats: nil,
+        history: nil,
+        config_file: nil,
+        exec_mode: nil,
+        help_requested: false
+      }
+    end
+
+    def build_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: rbwatch [options] command [args...]"
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "  rbwatch app.rb"
+        opts.separator "  rbwatch ruby app.rb"
+        opts.separator "  rbw app.rb"
+        opts.separator "  rbwatch bundle exec ruby app.rb"
+        opts.separator "  rbwatch --config rbwatch.yml ruby app.rb"
+        opts.separator ""
+        opts.separator "Options:"
+
+        opts.on("--delay MS", Integer, "Debounce delay in milliseconds (default 300)") { |value| options[:delay] = value }
+        opts.on("--ext EXTENSIONS", String, "Comma-separated extensions") { |value| options[:extensions] = split_csv(value) }
+        opts.on("--ignore PATHS", String, "Comma-separated ignored paths") { |value| options[:ignore] = split_csv(value) }
+        opts.on("--watch PATHS", String, "Comma-separated watch roots") { |value| options[:watch_paths] = split_csv(value) }
+        opts.on("--theme NAME", String, "Theme name: ruby, neon, minimal, matrix") { |value| options[:theme_name] = value }
+        opts.on("--clear", "Clear the terminal and scrollback before each restart") { options[:clear] = true }
+        opts.on("--no-clear", "Keep previous terminal output between restarts") { options[:clear] = false }
+        opts.on("--verbose", "Show additional logs") { options[:verbose] = true }
+        opts.on("--no-banner", "Hide the startup banner") { options[:banner] = false }
+        opts.on("--no-color", "Disable ANSI colors") { options[:color] = false }
+        opts.on("--sound", "Reserved for future sound notifications") { options[:sound] = true }
+        opts.on("--desktop-notify", "Reserved for desktop notifications") { options[:desktop_notify] = true }
+        opts.on("--stats", "Show restart count and uptime in the status card") { options[:stats] = true }
+        opts.on("--history", "Reserved for restart history") { options[:history] = true }
+        opts.on("--config PATH", String, "Load settings from a YAML configuration file") { |value| options[:config_file] = value }
+        opts.on("--exec", "Reserved for exec-mode launches") { options[:exec_mode] = true }
+        opts.on_tail("-h", "--help", "Show this help") { options[:help_requested] = true }
+      end
+    end
+
+    def split_csv(value)
+      value.to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/rbwatch/configuration.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require "yaml"
+
+module RBWatch
+  class Configuration
+    DEFAULT_DELAY = 300
+    DEFAULT_EXTENSIONS = %w[rb erb haml slim rake yml yaml json].freeze
+    DEFAULT_IGNORE = %w[log tmp .git node_modules].freeze
+    DEFAULT_WATCH_PATHS = ["."].freeze
+    CONFIG_FILENAMES = %w[rbwatch.yml rbwatch.yaml .rbwatch.yml .rbwatch.yaml].freeze
+    SHORTHAND_RUBY_EXTENSIONS = %w[.rb .ru].freeze
+
+    attr_reader :delay,
+                :extensions,
+                :ignore,
+                :watch_paths,
+                :command,
+                :clear,
+                :verbose,
+                :banner,
+                :color,
+                :theme_name,
+                :restart_on_exit,
+                :sound,
+                :desktop_notify,
+                :stats,
+                :history,
+                :config_file,
+                :exec_mode,
+                :stdin,
+                :stdout,
+                :stderr
+
+    class << self
+      def discover_config_file(cwd = Dir.pwd)
+        CONFIG_FILENAMES.map { |name| File.join(cwd, name) }.find { |path| File.file?(path) }
+      end
+
+      def load_file(path)
+        return {} if path.nil? || path.to_s.strip.empty?
+
+        raw = YAML.safe_load(File.read(path), permitted_classes: [Symbol], aliases: true)
+        raise ArgumentError, "Config file must contain a YAML mapping" unless raw.nil? || raw.is_a?(Hash)
+
+        normalize_config_hash(raw || {})
+      rescue Psych::SyntaxError => e
+        raise ArgumentError, "Unable to parse config file #{path}: #{e.message}"
+      end
+
+      def from_sources(cli_options:, command:, stdin:, stdout:, stderr:)
+        cli_options = symbolize_keys(cli_options)
+        explicit_config_file = cli_options.delete(:config_file)
+        config_path = explicit_config_file || discover_config_file
+        file_options = config_path ? load_file(config_path) : {}
+
+        merged = default_options.merge(file_options).merge(cli_options.compact)
+        resolved_command = command.empty? ? Array(merged[:command]) : command
+
+        new(
+          **merged.merge(command: resolved_command, config_file: config_path),
+          stdin: stdin,
+          stdout: stdout,
+          stderr: stderr
+        )
+      end
+
+      def default_options
+        {
+          delay: DEFAULT_DELAY,
+          extensions: DEFAULT_EXTENSIONS.dup,
+          ignore: DEFAULT_IGNORE.dup,
+          watch_paths: DEFAULT_WATCH_PATHS.dup,
+          command: [],
+          clear: nil,
+          verbose: false,
+          banner: true,
+          color: true,
+          theme_name: :ruby,
+          restart_on_exit: true,
+          sound: false,
+          desktop_notify: false,
+          stats: false,
+          history: false,
+          config_file: nil,
+          exec_mode: false
+        }
+      end
+
+      def normalize_config_hash(hash)
+        hash.each_with_object({}) do |(key, value), options|
+          case key.to_s
+          when "delay"
+            options[:delay] = value
+          when "extensions"
+            options[:extensions] = normalize_list(value)
+          when "ignore"
+            options[:ignore] = normalize_list(value)
+          when "watch_paths", "watch"
+            options[:watch_paths] = normalize_watch_paths(value)
+          when "command"
+            options[:command] = normalize_command(value)
+          when "clear", "verbose", "banner", "color", "restart_on_exit", "sound", "desktop_notify", "stats", "history", "exec_mode"
+            options[key.to_sym] = !!value
+          when "theme", "theme_name"
+            options[:theme_name] = Theme.normalize_name(value) || :ruby
+          end
+        end
+      end
+
+      def normalize_list(value)
+        Array(value).flat_map { |item| item.to_s.split(",") }
+                    .map { |entry| entry.strip.downcase }
+                    .reject(&:empty?)
+                    .uniq
+      end
+
+      def normalize_watch_paths(value)
+        paths = Array(value).flat_map { |item| item.to_s.split(",") }
+        normalized = paths.map { |path| path.strip }.reject(&:empty?)
+        normalized = ["."] if normalized.empty?
+        normalized.uniq
+      end
+
+      def normalize_command(value)
+        command = case value
+        when nil
+          []
+        when String
+          Shellwords.split(value)
+        else
+          Array(value).flat_map do |entry|
+            entry.is_a?(String) ? Shellwords.split(entry) : entry
+          end.map(&:to_s)
+        end
+        expand_command_shorthand(command)
+      end
+
+      def expand_command_shorthand(command)
+        return command if command.length != 1
+
+        first = command.first.to_s
+        return command unless ruby_script_path?(first)
+
+        ["ruby", first]
+      end
+
+      def ruby_script_path?(path)
+        SHORTHAND_RUBY_EXTENSIONS.include?(File.extname(path).downcase)
+      end
+
+      def symbolize_keys(hash)
+        hash.each_with_object({}) { |(key, value), result| result[key.to_sym] = value }
+      end
+    end
+
+    def initialize(
+      delay: DEFAULT_DELAY,
+      extensions: DEFAULT_EXTENSIONS,
+      ignore: DEFAULT_IGNORE,
+      watch_paths: DEFAULT_WATCH_PATHS,
+      command: [],
+      clear: nil,
+      verbose: false,
+      banner: true,
+      color: true,
+      theme_name: "ruby",
+      restart_on_exit: true,
+      sound: false,
+      desktop_notify: false,
+      stats: false,
+      history: false,
+      config_file: nil,
+      exec_mode: false,
+      stdin: $stdin,
+      stdout: $stdout,
+      stderr: $stderr
+    )
+      @delay = Integer(delay)
+      @extensions = normalize_list(extensions)
+      @ignore = normalize_list(ignore)
+      @watch_paths = normalize_watch_paths(watch_paths)
+      @command = normalize_command(command)
+      @verbose = !!verbose
+      @banner = !!banner
+      @color = !!color
+      @theme_name = Theme.normalize_name(theme_name) || :ruby
+      @restart_on_exit = !!restart_on_exit
+      @sound = !!sound
+      @desktop_notify = !!desktop_notify
+      @stats = !!stats
+      @history = !!history
+      @config_file = config_file
+      @exec_mode = !!exec_mode
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @clear = clear.nil? ? clear_by_default?(stderr) : !!clear
+      @theme = nil
+    end
+
+    def color?
+      @color
+    end
+
+    def verbose?
+      @verbose
+    end
+
+    def clear?
+      @clear
+    end
+
+    def banner?
+      @banner
+    end
+
+    def restart_on_exit?
+      @restart_on_exit
+    end
+
+    def sound?
+      @sound
+    end
+
+    def desktop_notify?
+      @desktop_notify
+    end
+
+    def stats?
+      @stats
+    end
+
+    def history?
+      @history
+    end
+
+    def exec_mode?
+      @exec_mode
+    end
+
+    def theme
+      @theme ||= Theme.resolve(theme_name, color: color?, interactive: interactive_theme_prompt?, input: stdin, output: stderr)
+    end
+
+    def delay_seconds
+      delay / 1000.0
+    end
+
+    def command_string
+      Shellwords.join(command)
+    end
+
+    def interactive_theme_prompt?
+      stdin.respond_to?(:tty?) && stdout.respond_to?(:tty?) && stdin.tty? && stdout.tty?
+    end
+
+    def to_h
+      {
+        delay: delay,
+        extensions: extensions.dup,
+        ignore: ignore.dup,
+        watch_paths: watch_paths.dup,
+        command: command.dup,
+        clear: clear?,
+        verbose: verbose?,
+        banner: banner?,
+        color: color?,
+        theme_name: theme_name,
+        restart_on_exit: restart_on_exit?,
+        sound: sound?,
+        desktop_notify: desktop_notify?,
+        stats: stats?,
+        history: history?,
+        config_file: config_file,
+        exec_mode: exec_mode?
+      }
+    end
+
+    private
+
+    def normalize_list(values)
+      self.class.normalize_list(values)
+    end
+
+    def normalize_watch_paths(values)
+      self.class.normalize_watch_paths(values)
+    end
+
+    def normalize_command(value)
+      self.class.normalize_command(value)
+    end
+
+    def clear_by_default?(stderr)
+      stderr.respond_to?(:tty?) && stderr.tty?
+    end
+  end
+end