rbwatch 1.0.0

data/lib/rbwatch/dashboard.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "tty-box"
+require "tty-cursor"
+require "tty-screen"
+require "tty-spinner"
+require "tty-table"
+
+module RBWatch
+  class Dashboard
+    FOOTER_MESSAGE = "Watching... Press CTRL+C to stop."
+    SCROLLBACK_CLEAR = "\e[3J"
+    STARTUP_TITLE = " RBWatch "
+    RESTART_TITLE = " 🔄 Changes detected "
+
+    def initialize(output:, theme:, clear: false)
+      @output = output
+      @theme = theme
+      @clear = clear
+    end
+
+    def clear_screen
+      return "" unless tty?
+
+      output.print SCROLLBACK_CLEAR
+      output.print TTY::Cursor.clear_screen
+      output.print TTY::Cursor.move_to(0, 0)
+      ""
+    end
+
+    def hide_cursor
+      return unless tty?
+
+      output.print TTY::Cursor.hide
+    end
+
+    def show_cursor
+      return unless tty?
+
+      output.print TTY::Cursor.show
+    end
+
+    def render_banner(version:, command:, watch_paths:, config_file: nil, theme_name: nil)
+      lines = [
+        theme.accent("RBWatch #{version}"),
+        theme.info("Delightful process restarts for Ruby projects"),
+        theme.muted("Command: #{command}"),
+        theme.muted("Watching: #{Array(watch_paths).join(', ')}")
+      ]
+      lines << theme.muted("Config: #{config_file}") if config_file
+      lines << theme.muted("Theme: #{theme_name}") if theme_name
+      frame = TTY::Box.frame(
+        lines.join("\n"),
+        width: box_width(lines),
+        align: :center,
+        padding: [1, 2],
+        title: { top_left: STARTUP_TITLE },
+        **theme.box_options(:banner)
+      )
+      output.puts frame
+      frame
+    end
+
+    def render_status(status:, files:, extensions:, delay:, pid:, command:, config_file: nil, theme_name: nil, stats: nil)
+      rows = [
+        [theme.label("Status"), theme.status(status)],
+        [theme.label("Files"), theme.files(files.to_s)],
+        [theme.label("Extensions"), theme.command(Array(extensions).join(", "))],
+        [theme.label("Delay"), theme.delay("#{delay}ms")],
+        [theme.label("PID"), theme.pid(pid.to_s)],
+        [theme.label("Command"), theme.command(command)]
+      ]
+      rows.insert(4, [theme.label("Theme"), theme.command(theme_name.to_s)]) if theme_name
+      rows.insert(5, [theme.label("Config"), theme.command(config_file.to_s)]) if config_file
+      if stats
+        rows.insert(4, [theme.label("Restarts"), theme.command(stats.fetch(:restarts).to_s)])
+        rows.insert(5, [theme.label("Uptime"), theme.command(stats.fetch(:uptime).to_s)])
+      end
+      table = TTY::Table.new(header: ["Field", "Value"], rows: rows)
+      body = table.render(:basic).lines.drop(1).map { |line| line.rstrip }
+      frame = render_table_frame(body, border: theme.border(:status))
+      output.puts frame
+      frame
+    end
+
+    def render_restart(change_set)
+      lines = [
+        theme.restart("Changes detected"),
+        theme.warning("Stopping previous process..."),
+        theme.info("Starting new process..."),
+        theme.success("Process started successfully")
+      ]
+      if change_set&.changed?
+        summary = change_set.paths.first(5).join(", ")
+        summary = "#{summary}, ..." if change_set.paths.length > 5
+        lines << theme.muted("Changed files: #{summary}")
+      end
+      frame = TTY::Box.frame(
+        lines.join("\n"),
+        width: box_width(lines),
+        align: :center,
+        padding: [1, 2],
+        title: { top_left: RESTART_TITLE },
+        **theme.box_options(:restart)
+      )
+      output.puts frame
+      frame
+    end
+
+    def render_footer
+      line = theme.muted(FOOTER_MESSAGE)
+      output.puts line
+      line
+    end
+
+    def log_info(message)
+      log(:info, message)
+    end
+
+    def log_success(message)
+      log(:success, message)
+    end
+
+    def log_warning(message)
+      log(:warning, message)
+    end
+
+    def log_error(message)
+      log(:error, message)
+    end
+
+    def log_restart(message)
+      log(:restart, message)
+    end
+
+    def spinner(message)
+      if tty?
+        TTY::Spinner.new("[:spinner] #{message}", format: :spin, output: output)
+      else
+        NullSpinner.new(self)
+      end
+    end
+
+    private
+
+    def box_width(content, minimum: 48)
+      lines = Array(content).flat_map { |line| line.to_s.lines }
+      visible_width = lines.map { |line| line.uncolorize.rstrip.length }.max || minimum
+      width = [visible_width + 4, screen_width - 2].min
+      [width, minimum].max
+    end
+
+    def render_table_frame(lines, border:)
+      visible_width = lines.map { |line| line.uncolorize.rstrip.length }.max || 0
+      chars = box_chars(border)
+      horizontal = chars[:line] * (visible_width + 2)
+
+      framed = []
+      framed << theme.muted("#{chars[:top_left]}#{horizontal}#{chars[:top_right]}")
+
+      lines.each do |line|
+        padding = visible_width - line.uncolorize.rstrip.length
+        framed << [
+          theme.muted(chars[:pipe]),
+          " ",
+          line,
+          " " * padding,
+          " ",
+          theme.muted(chars[:pipe])
+        ].join
+      end
+
+      framed << theme.muted("#{chars[:bottom_left]}#{horizontal}#{chars[:bottom_right]}")
+      framed.join("\n")
+    end
+
+    def box_chars(border)
+      {
+        top_left: TTY::Box.corner_top_left_char(border),
+        top_right: TTY::Box.corner_top_right_char(border),
+        bottom_left: TTY::Box.corner_bottom_left_char(border),
+        bottom_right: TTY::Box.corner_bottom_right_char(border),
+        line: TTY::Box.line_char(border),
+        pipe: TTY::Box.pipe_char(border)
+      }
+    end
+
+    attr_reader :output, :theme, :clear
+
+    def tty?
+      output.respond_to?(:tty?) && output.tty?
+    end
+
+    def screen_width
+      TTY::Screen.width
+    rescue StandardError
+      80
+    end
+
+    def log(level, message)
+      line = "#{theme.timestamp} #{theme.prefix(level)} #{colorized_message(level, message)}"
+      output.puts line
+      line
+    end
+
+    def colorized_message(level, message)
+      case level
+      when :success then theme.success(message)
+      when :warning then theme.warning(message)
+      when :error then theme.error(message)
+      when :restart then theme.restart(message)
+      else theme.info(message)
+      end
+    end
+
+    class NullSpinner
+      def initialize(dashboard)
+        @dashboard = dashboard
+      end
+
+      def auto_spin
+        true
+      end
+
+      def success(message = nil)
+        @dashboard.log_success(message) if message
+        true
+      end
+
+      def error(message = nil)
+        @dashboard.log_error(message) if message
+        true
+      end
+
+      def stop
+        true
+      end
+
+      def kill
+        true
+      end
+    end
+  end
+end

data/lib/rbwatch/file_scanner.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module RBWatch
+  class FileScanner
+    ChangeSet = Struct.new(:added_paths, :removed_paths, :modified_paths, keyword_init: true) do
+      def initialize(**kwargs)
+        super
+        self.added_paths ||= []
+        self.removed_paths ||= []
+        self.modified_paths ||= []
+      end
+
+      def changed?
+        added_paths.any? || removed_paths.any? || modified_paths.any?
+      end
+
+      def total
+        added_paths.length + removed_paths.length + modified_paths.length
+      end
+
+      def paths
+        (added_paths + removed_paths + modified_paths).uniq
+      end
+    end
+
+    attr_reader :configuration
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def watchable_files
+      files = configuration.watch_paths.flat_map do |root|
+        Dir.glob(File.join(root, "**", "*"))
+      end
+
+      files.uniq.select { |path| watchable_file?(path) }.map { |path| normalize_path(path) }.sort
+    end
+
+    def scan
+      watchable_files.each_with_object({}) do |path, snapshot|
+        snapshot[path] = mtime_for(path)
+      rescue Errno::ENOENT
+        next
+      end
+    end
+
+    def diff(previous_snapshot, current_snapshot = scan)
+      previous_snapshot ||= {}
+      current_snapshot ||= {}
+
+      previous_paths = previous_snapshot.keys
+      current_paths = current_snapshot.keys
+
+      added = current_paths - previous_paths
+      removed = previous_paths - current_paths
+      modified = (previous_paths & current_paths).select do |path|
+        previous_snapshot[path] != current_snapshot[path]
+      end
+
+      ChangeSet.new(
+        added_paths: added.sort,
+        removed_paths: removed.sort,
+        modified_paths: modified.sort
+      )
+    end
+
+    def count
+      watchable_files.length
+    end
+
+    private
+
+    def watchable_file?(path)
+      normalized = normalize_path(path)
+      return false unless File.file?(path)
+
+      return false if ignored_path?(normalized)
+
+      extension = File.extname(normalized).delete_prefix(".").downcase
+      return false if extension.empty?
+
+      configuration.extensions.include?(extension)
+    end
+
+    def ignored_path?(path)
+      segments = Pathname.new(path).each_filename.to_a.map(&:downcase)
+      segments.any? { |segment| configuration.ignore.include?(segment) }
+    end
+
+    def mtime_for(path)
+      File.mtime(path).to_f
+    end
+
+    def normalize_path(path)
+      Pathname.new(path).cleanpath.to_s
+    end
+  end
+end

data/lib/rbwatch/process_manager.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RBWatch
+  class ProcessManager
+    DEFAULT_GRACE_PERIOD = 2.0
+    DEFAULT_KILL_TIMEOUT = 5.0
+
+    attr_reader :pid, :last_status, :command
+
+    def initialize(
+      command:,
+      stdout: $stdout,
+      stderr: $stderr,
+      grace_period: DEFAULT_GRACE_PERIOD,
+      kill_timeout: DEFAULT_KILL_TIMEOUT,
+      chdir: Dir.pwd
+    )
+      @command = Array(command).map(&:to_s)
+      @child_stdout = stdout
+      @child_stderr = stderr
+      @grace_period = grace_period.to_f
+      @kill_timeout = kill_timeout.to_f
+      @chdir = chdir
+      @pid = nil
+      @last_status = nil
+    end
+
+    def start
+      raise ArgumentError, "command cannot be empty" if command.empty?
+
+      stop if running?
+      @last_status = nil
+      @pid = spawn_process
+    end
+
+    def stop
+      current_pid = @pid
+      return @last_status unless current_pid
+
+      status = terminate_process(current_pid)
+      @pid = nil
+      @last_status = status if status
+      status
+    end
+
+    def restart
+      stop
+      start
+    end
+
+    def running?
+      poll_status
+      !@pid.nil?
+    end
+
+    def poll_status
+      current_pid = @pid
+      return nil unless current_pid
+
+      waited_pid, status = Process.waitpid2(current_pid, Process::WNOHANG)
+      return nil unless waited_pid
+
+      @pid = nil
+      @last_status = status
+      status
+    rescue Errno::ECHILD
+      @pid = nil
+      nil
+    end
+
+    private
+
+    def spawn_process
+      Process.spawn(
+        *command,
+        chdir: @chdir,
+        out: @child_stdout,
+        err: @child_stderr,
+        pgroup: true
+      )
+    end
+
+    def terminate_process(current_pid)
+      terminate_pid(current_pid)
+      status = wait_for_exit(current_pid, @grace_period)
+      return status if status
+
+      terminate_group(current_pid)
+      status = wait_for_exit(current_pid, [@kill_timeout - @grace_period, 0].max)
+      return status if status
+
+      kill_pid(current_pid)
+      kill_group(current_pid)
+      wait_for_exit(current_pid, 0.5)
+    end
+
+    def wait_for_exit(current_pid, timeout)
+      deadline = monotonic_now + timeout
+
+      loop do
+        waited_pid, status = Process.waitpid2(current_pid, Process::WNOHANG)
+        return status if waited_pid
+
+        break if monotonic_now >= deadline
+
+        sleep 0.05
+      end
+
+      nil
+    rescue Errno::ECHILD
+      @last_status
+    end
+
+    def terminate_pid(current_pid)
+      Process.kill("TERM", current_pid)
+    rescue Errno::ESRCH
+      nil
+    end
+
+    def terminate_group(current_pid)
+      Process.kill("TERM", -current_pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    def kill_pid(current_pid)
+      Process.kill("KILL", current_pid)
+    rescue Errno::ESRCH
+      nil
+    end
+
+    def kill_group(current_pid)
+      Process.kill("KILL", -current_pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/rbwatch/runner.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module RBWatch
+  class Runner
+    CRASH_LOOP_THRESHOLD = 1.0
+
+    def initialize(configuration:, dashboard: nil, scanner: nil, process_manager: nil, watcher: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @configuration = configuration
+      @theme = configuration.theme
+      @dashboard = dashboard || Dashboard.new(output: configuration.stderr, theme: @theme, clear: configuration.clear?)
+      @scanner = scanner || FileScanner.new(configuration)
+      @process_manager = process_manager || ProcessManager.new(
+        command: configuration.command,
+        stdout: configuration.stdout,
+        stderr: configuration.stderr
+      )
+      @watcher = watcher || Watcher.new(
+        scanner: @scanner,
+        delay: configuration.delay,
+        poll_interval: poll_interval
+      )
+      @clock = clock
+      @started_at = current_time
+      @process_started_at = nil
+      @restart_count = 0
+      @shutdown_requested = false
+      @restart_suspended = false
+      @previous_signal_handlers = {}
+    end
+
+    def run
+      ensure_command!
+      install_signal_handlers
+
+      dashboard.clear_screen if configuration.clear?
+      dashboard.hide_cursor
+
+      dashboard.render_banner(
+        version: VERSION,
+        command: configuration.command_string,
+        watch_paths: configuration.watch_paths,
+        config_file: configuration.config_file,
+        theme_name: configuration.theme_name
+      ) if configuration.banner?
+
+      dashboard.log_info("Starting process...")
+      dashboard.log_info("Watching #{scanner.count} files")
+      dashboard.log_info("Loaded config file: #{configuration.config_file}") if configuration.config_file
+      dashboard.log_info("Extensions: #{configuration.extensions.join(', ')}") if configuration.verbose?
+      dashboard.log_info("Ignoring: #{configuration.ignore.join(', ')}") if configuration.verbose?
+      dashboard.log_info("Theme: #{configuration.theme_name}") if configuration.verbose?
+
+      spinner = dashboard.spinner("Starting application...")
+      spinner.auto_spin
+      process_manager.start
+      mark_process_started
+      spinner.success("Application started")
+
+      dashboard.log_success("Process started (PID #{process_manager.pid})")
+      render_status_card
+      dashboard.render_footer
+
+      watcher.reset(scanner.scan)
+      watch_loop
+
+      0
+    rescue Theme::UnknownThemeError => e
+      dashboard.log_error(e.message)
+      1
+    rescue StandardError => e
+      dashboard.log_error("#{e.class}: #{e.message}")
+      dashboard.log_error(e.backtrace.first) if configuration.verbose? && e.backtrace
+      1
+    ensure
+      dashboard.log_warning("Received #{@shutdown_signal}, shutting down...") if @shutdown_signal
+      watcher.stop
+      process_manager.stop
+      dashboard.show_cursor
+      restore_signal_handlers
+    end
+
+    private
+
+    attr_reader :configuration, :dashboard, :scanner, :process_manager, :watcher
+
+    def ensure_command!
+      raise ArgumentError, "rbwatch requires a command to run" if configuration.command.empty?
+    end
+
+    def poll_interval
+      [configuration.delay_seconds / 3.0, 0.1].min
+    end
+
+    def install_signal_handlers
+      %w[INT TERM].each do |signal|
+        @previous_signal_handlers[signal] = Signal.trap(signal) { request_shutdown(signal) }
+      end
+    end
+
+    def restore_signal_handlers
+      @previous_signal_handlers.each do |signal, handler|
+        Signal.trap(signal, handler)
+      end
+    end
+
+    def request_shutdown(signal)
+      @shutdown_signal = signal
+      @shutdown_requested = true
+    end
+
+    def shutdown_requested?
+      @shutdown_requested
+    end
+
+    def watch_loop
+      until shutdown_requested?
+        if (status = process_manager.poll_status)
+          handle_process_exit(status)
+          next
+        end
+
+        if (event = watcher.step)
+          handle_change_event(event)
+          next
+        end
+
+        sleep watcher.poll_interval
+      end
+    end
+
+    def handle_process_exit(status)
+      dashboard.clear_screen if configuration.clear?
+      description = exit_description(status)
+      dashboard.log_warning("Process exited #{description}")
+
+      if quick_exit? && configuration.restart_on_exit?
+        @restart_suspended = true
+        dashboard.log_warning("Process exited too quickly; waiting for file changes before restarting.")
+        return
+      end
+
+      @restart_suspended = false
+
+      unless configuration.restart_on_exit?
+        @shutdown_requested = true
+        return
+      end
+
+      dashboard.log_restart("Restarting application after exit...")
+      restart_process
+    end
+
+    def handle_change_event(event)
+      dashboard.clear_screen if configuration.clear?
+      dashboard.log_restart("Changes detected")
+      dashboard.render_restart(event.change_set)
+      restart_process
+    end
+
+    def restart_process
+      spinner = dashboard.spinner("Starting application...")
+      spinner.auto_spin
+      process_manager.restart
+      mark_process_started
+      @restart_count += 1
+      @restart_suspended = false
+      spinner.success("Application started")
+
+      dashboard.log_success("Process started (PID #{process_manager.pid})")
+      render_status_card
+      dashboard.render_footer
+      watcher.reset(scanner.scan)
+    end
+
+    def render_status_card
+      dashboard.render_status(
+        status: "Watching",
+        files: scanner.count,
+        extensions: configuration.extensions,
+        delay: configuration.delay,
+        pid: process_manager.pid,
+        command: configuration.command_string,
+        config_file: configuration.config_file,
+        theme_name: configuration.theme_name,
+        stats: stats_snapshot
+      )
+    end
+
+    def exit_description(status)
+      if status.respond_to?(:signaled?) && status.signaled?
+        "by signal #{status.termsig}"
+      elsif status.respond_to?(:exitstatus) && !status.exitstatus.nil?
+        "with status #{status.exitstatus}"
+      else
+        "unexpectedly"
+      end
+    end
+
+    def stats_snapshot
+      return nil unless configuration.stats?
+
+      {
+        restarts: @restart_count,
+        uptime: format_duration(elapsed_seconds)
+      }
+    end
+
+    def elapsed_seconds
+      current_time - @started_at
+    end
+
+    def format_duration(total_seconds)
+      total = total_seconds.to_i
+      hours = total / 3600
+      minutes = (total % 3600) / 60
+      seconds = total % 60
+
+      format("%02d:%02d:%02d", hours, minutes, seconds)
+    end
+
+    def quick_exit?
+      return false unless @process_started_at
+
+      process_uptime < CRASH_LOOP_THRESHOLD
+    end
+
+    def process_uptime
+      current_time - @process_started_at
+    end
+
+    def mark_process_started
+      @process_started_at = current_time
+    end
+
+    def current_time
+      @clock.call
+    end
+  end
+end