sktop 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a3ed9a8721d477335f08d009c76cd65793b96ab0c0a045466ebdfa05a5e7f12
-  data.tar.gz: cba94dc737356f0b9295cc04c00155dd2cc7eb60372dec1774b60489ae4c476d
+  metadata.gz: d1e0891fc2a69763f5784c7cc96fc69103d14362aa67a08b82b6c13aa578985b
+  data.tar.gz: fea7b7284c37d666516d42c2bcc97e0f6b3db4cbb53628e2e3b35c6521c44845
 SHA512:
-  metadata.gz: e26bc9fe20fdb3d540c417802ca15db53b5263f52dcab6f696afb1b4cf6d52134e8dafe6d09abf8378e694fdb5c0307c61b7c84a0e523aee12f9db5b2cb00bd1
-  data.tar.gz: 93eac6acd09dda870a90311fbd606a54ee7ad072919bba959951ecec91e31eb75d01e4a851aec1f111f9e0f193328c0f02e3adad914a15afdd17c67c02ec6ea5
+  metadata.gz: 59b4378e2dae18d69bcbd9c3a6492ff0bcad4d830ad9d0c893fa0b9f70f6845d87b6652dcc850d7a02efaea10c00343203d8b495c8eded6318a9b6c648e1fb5e
+  data.tar.gz: eb54c39df9aa1ec70bcb719b11a7ab0aac88970586345793e890b67dda9f753f207e8f7e5ea0923153118b66c59952f60ff46309e28da281e2bc4f87cbd48c4a

data/lib/sktop/cli.rb

@@ -7,7 +7,18 @@ require "io/console"
 require "io/wait"
 
 module Sktop
+  # Command-line interface for the Sktop Sidekiq monitor.
+  # Handles argument parsing, Redis configuration, and the main event loop.
+  #
+  # @example Basic usage
+  #   Sktop::CLI.new.run
+  #
+  # @example With custom arguments
+  #   Sktop::CLI.new(["-r", "redis://myhost:6379/1", "-q"]).run
   class CLI
+    # Create a new CLI instance.
+    #
+    # @param args [Array<String>] command-line arguments (defaults to ARGV)
     def initialize(args = ARGV)
       @args = args
       @options = {
@@ -20,6 +31,11 @@ module Sktop
       @running = true
     end
 
+    # Run the CLI application.
+    # Parses options, configures Redis, and starts the TUI.
+    #
+    # @return [void]
+    # @raise [SystemExit] on connection errors or interrupts
     def run
       parse_options!
       configure_redis
@@ -39,6 +55,10 @@ module Sktop
       exit 1
     end
 
+    # Gracefully shutdown the application.
+    # Restores terminal state and shows the cursor.
+    #
+    # @return [void]
     def shutdown
       @running = false
       print "\e[?25h"    # Show cursor
@@ -48,6 +68,9 @@ module Sktop
 
     private
 
+    # Parse command-line options and populate @options hash.
+    # @return [void]
+    # @api private
     def parse_options!
       parser = OptionParser.new do |opts|
         opts.banner = "Usage: sktop [options]"
@@ -117,6 +140,9 @@ module Sktop
       parser.parse!(@args)
     end
 
+    # Configure Sidekiq's Redis connection from CLI options.
+    # @return [void]
+    # @api private
     def configure_redis
       Sidekiq.configure_client do |config|
         if @options[:namespace]
@@ -130,6 +156,10 @@ module Sktop
       end
     end
 
+    # Start the main TUI loop with background data fetching.
+    # Handles both one-shot mode and interactive auto-refresh mode.
+    # @return [void]
+    # @api private
     def start_watcher
       collector = StatsCollector.new
       @display = Display.new
@@ -195,7 +225,17 @@ module Sktop
               scheduled_jobs: collector.scheduled_jobs(limit: 500),
               dead_jobs: collector.dead_jobs(limit: 500)
             }
+
+            # If viewing queue jobs, refresh that data too
+            if @display.current_view == :queue_jobs && @display.selected_queue
+              snapshot[:queue_jobs] = collector.queue_jobs(@display.selected_queue, limit: 500)
+            end
+
             @data_mutex.synchronize do
+              # Preserve queue_jobs if not refreshed above but still in that view
+              if @cached_data && @cached_data[:queue_jobs] && !snapshot[:queue_jobs]
+                snapshot[:queue_jobs] = @cached_data[:queue_jobs]
+              end
               @cached_data = snapshot
               @data_version += 1
             end
@@ -257,6 +297,10 @@ module Sktop
       end
     end
 
+    # Render the display from the cached data snapshot.
+    # Shows loading screen if no data is available yet.
+    # @return [void]
+    # @api private
     def render_cached_data
       data = @data_mutex.synchronize { @cached_data }
       if data
@@ -266,6 +310,13 @@ module Sktop
       end
     end
 
+    # Handle a keyboard input event.
+    # Routes to appropriate view or action handler.
+    #
+    # @param key [String] the key character pressed
+    # @param stdin [IO] the stdin IO object for reading escape sequences
+    # @return [void]
+    # @api private
     def handle_keypress(key, stdin)
       case key
       when 'q', 'Q'
@@ -282,6 +333,8 @@ module Sktop
         @display.current_view = :dead
       when 'm', 'M'
         @display.current_view = :main
+      when "\r", "\n"  # Enter key
+        handle_enter_action
       when "\x12"  # Ctrl+R - retry job
         handle_retry_action
       when "\x18"  # Ctrl+X - delete job
@@ -299,8 +352,10 @@ module Sktop
             @display.select_up
           when "[B"  # Down arrow
             @display.select_down
-          when "[C"  # Right arrow (unused for now)
-          when "[D"  # Left arrow (unused for now)
+          when "[C"  # Right arrow - next view
+            @display.next_view
+          when "[D"  # Left arrow - previous view
+            @display.previous_view
           when "[5~"  # Page Up
             @display.page_up
           when "[6~"  # Page Down
@@ -310,18 +365,22 @@ module Sktop
           when "x", "X"  # Alt+X - Delete All
             handle_delete_all_action
           else
-            # Just Escape key - go to main
-            @display.current_view = :main
+            # Just Escape key - go back or to main
+            handle_escape_action
           end
         else
-          # Just Escape key - go to main
-          @display.current_view = :main
+          # Just Escape key - go back or to main
+          handle_escape_action
         end
       when "\u0003"  # Ctrl+C
         raise Interrupt
       end
     end
 
+    # Handle Ctrl+R to retry the selected job.
+    # Only works in retries and dead views.
+    # @return [void]
+    # @api private
     def handle_retry_action
       return unless [:retries, :dead].include?(@display.current_view)
 
@@ -361,7 +420,17 @@ module Sktop
       end
     end
 
+    # Handle Ctrl+X to delete the selected job.
+    # Works in retries, dead, and queue_jobs views.
+    # @return [void]
+    # @api private
     def handle_delete_action
+      # Handle queue_jobs view separately
+      if @display.current_view == :queue_jobs
+        handle_delete_queue_job_action
+        return
+      end
+
       return unless [:retries, :dead].include?(@display.current_view)
 
       data = @data_mutex.synchronize { @cached_data }
@@ -400,6 +469,10 @@ module Sktop
       end
     end
 
+    # Handle Alt+R to retry all jobs in the current view.
+    # Only works in retries and dead views.
+    # @return [void]
+    # @api private
     def handle_retry_all_action
       return unless [:retries, :dead].include?(@display.current_view)
 
@@ -413,6 +486,10 @@ module Sktop
       end
     end
 
+    # Handle Alt+X to delete all jobs in the current view.
+    # Only works in retries and dead views.
+    # @return [void]
+    # @api private
     def handle_delete_all_action
       return unless [:retries, :dead].include?(@display.current_view)
 
@@ -426,6 +503,10 @@ module Sktop
       end
     end
 
+    # Handle Ctrl+Q to quiet the selected Sidekiq process.
+    # Only works in processes view.
+    # @return [void]
+    # @api private
     def handle_quiet_process_action
       return unless @display.current_view == :processes
 
@@ -463,6 +544,10 @@ module Sktop
       end
     end
 
+    # Handle Ctrl+K to stop/kill the selected Sidekiq process.
+    # Only works in processes view.
+    # @return [void]
+    # @api private
     def handle_stop_process_action
       return unless @display.current_view == :processes
 
@@ -500,5 +585,116 @@ module Sktop
       end
     end
 
+    # Handle Enter key to view jobs in the selected queue.
+    # Only works in queues view.
+    # @return [void]
+    # @api private
+    def handle_enter_action
+      return unless @display.current_view == :queues
+
+      data = @data_mutex.synchronize { @cached_data }
+      unless data
+        @display.set_status("No data available")
+        return
+      end
+
+      queues = data[:queues]
+      selected_idx = @display.selected_index
+
+      if queues.empty?
+        @display.set_status("No queues")
+        return
+      end
+
+      if selected_idx >= queues.length
+        @display.set_status("Invalid selection")
+        return
+      end
+
+      queue = queues[selected_idx]
+      queue_name = queue[:name]
+
+      # Fetch jobs from the queue
+      begin
+        collector = StatsCollector.new
+        jobs = collector.queue_jobs(queue_name, limit: 500)
+
+        # Update cached data with queue jobs
+        @data_mutex.synchronize do
+          @cached_data[:queue_jobs] = jobs
+        end
+
+        @display.selected_queue = queue_name
+        @display.current_view = :queue_jobs
+        @display.set_status("Loaded #{jobs.length} jobs from #{queue_name}")
+      rescue => e
+        @display.set_status("Error loading queue: #{e.message}")
+      end
+    end
+
+    # Handle Escape key to go back or return to main view.
+    # From queue_jobs returns to queues, otherwise returns to main.
+    # @return [void]
+    # @api private
+    def handle_escape_action
+      if @display.current_view == :queue_jobs
+        # Go back to queues view
+        @display.current_view = :queues
+        @display.selected_queue = nil
+      else
+        # Go to main view
+        @display.current_view = :main
+      end
+    end
+
+    # Handle Ctrl+X to delete a job from the current queue.
+    # Only works in queue_jobs view.
+    # @return [void]
+    # @api private
+    def handle_delete_queue_job_action
+      return unless @display.current_view == :queue_jobs
+
+      data = @data_mutex.synchronize { @cached_data }
+      unless data
+        @display.set_status("No data available")
+        return
+      end
+
+      jobs = data[:queue_jobs] || []
+      selected_idx = @display.selected_index
+      queue_name = @display.selected_queue
+
+      if jobs.empty?
+        @display.set_status("No jobs to delete")
+        return
+      end
+
+      if selected_idx >= jobs.length
+        @display.set_status("Invalid selection")
+        return
+      end
+
+      job = jobs[selected_idx]
+      unless job[:jid]
+        @display.set_status("Job has no JID")
+        return
+      end
+
+      begin
+        Sktop::JobActions.delete_queue_job(queue_name, job[:jid])
+        @display.set_status("Deleted #{job[:class]}")
+
+        # Refresh the queue jobs
+        collector = StatsCollector.new
+        new_jobs = collector.queue_jobs(queue_name, limit: 500)
+        @data_mutex.synchronize do
+          @cached_data[:queue_jobs] = new_jobs
+        end
+        @rendered_version = -1
+      rescue => e
+        @display.set_status("Error: #{e.message}")
+      end
+    end
+
   end
 end

data/lib/sktop/display.rb

@@ -1,9 +1,24 @@
 # frozen_string_literal: true
 
 module Sktop
+  # Handles all terminal display rendering for the Sktop TUI.
+  # Manages views, scrolling, selection, and ANSI-colored output.
+  #
+  # @example Basic usage
+  #   display = Sktop::Display.new
+  #   display.current_view = :queues
+  #   display.render(collector)
+  #
+  # @example With cached data for auto-refresh
+  #   display = Sktop::Display.new
+  #   display.render_refresh_from_cache(data_hash)
   class Display
+    # @return [Symbol] the current view (:main, :queues, :processes, :workers, :retries, :scheduled, :dead, :queue_jobs)
+    # @return [Symbol] the connection status (:connecting, :connected, :updating, :error)
+    # @return [Time, nil] the timestamp of the last successful data update
     attr_accessor :current_view, :connection_status, :last_update
 
+    # Create a new Display instance with default settings.
     def initialize
       @pastel = Pastel.new
       @cursor = TTY::Cursor
@@ -15,16 +30,26 @@ module Sktop
       @status_time = nil
       @connection_status = :connecting  # :connecting, :connected, :updating, :error
       @last_update = nil
+      @selected_queue = nil  # Track which queue is being viewed in queue_jobs view
     end
 
+    # @return [String, nil] the name of the currently selected queue (for queue_jobs view)
+    attr_accessor :selected_queue
+
+    # Scroll the current view up by one line.
+    # @return [Integer] the new scroll offset
     def scroll_up
       @scroll_offsets[@current_view] = [@scroll_offsets[@current_view] - 1, 0].max
     end
 
+    # Scroll the current view down by one line.
+    # @return [Integer] the new scroll offset
     def scroll_down
       @scroll_offsets[@current_view] += 1
     end
 
+    # Move selection up in selectable views, or scroll up in non-selectable views.
+    # @return [Integer] the new selected index or scroll offset
     def select_up
       if selectable_view?
         @selected_index[@current_view] = [@selected_index[@current_view] - 1, 0].max
@@ -33,6 +58,8 @@ module Sktop
       end
     end
 
+    # Move selection down in selectable views, or scroll down in non-selectable views.
+    # @return [Integer] the new selected index or scroll offset
     def select_down
       if selectable_view?
         @selected_index[@current_view] += 1
@@ -41,10 +68,15 @@ module Sktop
       end
     end
 
+    # Check if the current view supports item selection.
+    # @return [Boolean] true if the view supports selection
     def selectable_view?
-      [:processes, :retries, :dead].include?(@current_view)
+      [:queues, :queue_jobs, :processes, :retries, :dead].include?(@current_view)
     end
 
+    # Move up by one page in the current view.
+    # @param page_size [Integer, nil] custom page size (defaults to terminal height - 8)
+    # @return [Integer] the new selected index or scroll offset
     def page_up(page_size = nil)
       page_size ||= default_page_size
       if selectable_view?
@@ -54,6 +86,9 @@ module Sktop
       end
     end
 
+    # Move down by one page in the current view.
+    # @param page_size [Integer, nil] custom page size (defaults to terminal height - 8)
+    # @return [Integer] the new selected index or scroll offset
     def page_down(page_size = nil)
       page_size ||= default_page_size
       if selectable_view?
@@ -63,39 +98,77 @@ module Sktop
       end
     end
 
+    # Calculate the default page size based on terminal height.
+    # @return [Integer] the page size (minimum 5)
     def default_page_size
       # Use terminal height minus header/footer overhead as page size
       [terminal_height - 8, 5].max
     end
 
+    # Get the currently selected index for the current view.
+    # @return [Integer] the selected index (0-based)
     def selected_index
       @selected_index[@current_view]
     end
 
+    # Set a temporary status message to display.
+    # The message will be shown for approximately 3 seconds.
+    # @param message [String] the status message to display
+    # @return [void]
     def set_status(message)
       @status_message = message
       @status_time = Time.now
     end
 
+    # Reset the scroll offset for the current view to zero.
+    # @return [Integer] 0
     def reset_scroll
       @scroll_offsets[@current_view] = 0
     end
 
+    # Set the current view, preserving scroll position.
+    # @param view [Symbol] the view to switch to
+    # @return [Symbol] the new current view
     def current_view=(view)
       @current_view = view
       # Don't reset scroll when switching views - preserve position
     end
 
+    # Ordered list of views for cycling with arrow keys.
+    # @return [Array<Symbol>] the view order
+    VIEW_ORDER = [:main, :queues, :processes, :workers, :retries, :scheduled, :dead].freeze
+
+    # Switch to the next view in the cycle.
+    # @return [Symbol] the new current view
+    def next_view
+      current_idx = VIEW_ORDER.index(@current_view) || 0
+      @current_view = VIEW_ORDER[(current_idx + 1) % VIEW_ORDER.length]
+    end
+
+    # Switch to the previous view in the cycle.
+    # @return [Symbol] the new current view
+    def previous_view
+      current_idx = VIEW_ORDER.index(@current_view) || 0
+      @current_view = VIEW_ORDER[(current_idx - 1) % VIEW_ORDER.length]
+    end
+
+    # Reset cursor to top-left and hide it.
+    # @return [void]
     def reset_cursor
       print @cursor.move_to(0, 0)
       print @cursor.hide
       $stdout.flush
     end
 
+    # Show the cursor (call on exit).
+    # @return [void]
     def show_cursor
       print @cursor.show
     end
 
+    # Update the cached terminal size from TTY::Screen.
+    # Call this before entering raw mode or when terminal resizes.
+    # @return [Array<Integer>, nil] [height, width] or nil if unchanged
     def update_terminal_size
       # Force refresh of terminal size using TTY::Screen
       height = TTY::Screen.height
@@ -105,16 +178,26 @@ module Sktop
       end
     end
 
+    # Render the current view as a string (for one-shot mode).
+    # @param collector [StatsCollector, CachedData] the data source
+    # @return [String] the rendered output
     def render(collector)
       content_parts = build_output(collector)
       content_parts.reject { |p| p == :footer }.map(&:to_s).join("\n")
     end
 
+    # Render the current view directly to the terminal with screen clearing.
+    # @param collector [StatsCollector] the data source
+    # @return [void]
     def render_refresh(collector)
       content = build_output(collector)
       render_with_overwrite(content)
     end
 
+    # Render the current view from cached data hash.
+    # Updates connection status and last update time.
+    # @param data [Hash] cached data hash with :overview, :queues, :processes, etc.
+    # @return [void]
     def render_refresh_from_cache(data)
       @connection_status = :connected
       @last_update = Time.now
@@ -123,6 +206,8 @@ module Sktop
       render_with_overwrite(content)
     end
 
+    # Render a loading screen while waiting for initial data.
+    # @return [void]
     def render_loading
       lines = []
       lines << header_bar
@@ -134,39 +219,61 @@ module Sktop
       render_with_overwrite(lines)
     end
 
-    # Simple wrapper to make cached hash act like collector
+    # Wrapper class to make a cached data hash act like a StatsCollector.
+    # Provides the same interface methods that Display expects.
+    #
+    # @example
+    #   cached = CachedData.new({ overview: {...}, queues: [...] })
+    #   cached.overview  # => {...}
     class CachedData
+      # Create a new CachedData wrapper.
+      # @param data [Hash] the raw data hash
       def initialize(data)
         @data = data
       end
 
+      # @return [Hash] overview statistics
       def overview
         @data[:overview]
       end
 
+      # @return [Array<Hash>] queue information
       def queues
         @data[:queues]
       end
 
+      # @return [Array<Hash>] process information
       def processes
         @data[:processes]
       end
 
+      # @return [Array<Hash>] worker information
       def workers
         @data[:workers]
       end
 
+      # @param limit [Integer] maximum jobs to return
+      # @return [Array<Hash>] retry job information
       def retry_jobs(limit: 50)
         @data[:retry_jobs]&.first(limit) || []
       end
 
+      # @param limit [Integer] maximum jobs to return
+      # @return [Array<Hash>] scheduled job information
       def scheduled_jobs(limit: 50)
         @data[:scheduled_jobs]&.first(limit) || []
       end
 
+      # @param limit [Integer] maximum jobs to return
+      # @return [Array<Hash>] dead job information
       def dead_jobs(limit: 50)
         @data[:dead_jobs]&.first(limit) || []
       end
+
+      # @return [Array<Hash>] cached queue jobs data
+      def queue_jobs_cache
+        @data[:queue_jobs] || []
+      end
     end
 
     private
@@ -175,6 +282,8 @@ module Sktop
       case @current_view
       when :queues
         build_queues_detail(collector)
+      when :queue_jobs
+        build_queue_jobs_detail(collector)
       when :processes
         build_processes_detail(collector)
       when :workers
@@ -243,9 +352,24 @@ module Sktop
       lines = []
       lines << header_bar
       lines << ""
-      # Calculate available rows: height - header(1) - blank(1) - section(1) - table_header(1) - footer(1) = height - 5
-      max_rows = terminal_height - 5
-      queues_scrollable(collector.queues, max_rows).each_line(chomp: true) { |l| lines << l }
+      stats_meters(collector.overview, collector.processes).each_line(chomp: true) { |l| lines << l }
+      lines << ""
+      # Calculate available rows: height - header(1) - blank(1) - stats(6) - blank(1) - section(1) - table_header(1) - footer(1) = height - 12
+      max_rows = terminal_height - 12
+      queues_selectable(collector.queues, max_rows).each_line(chomp: true) { |l| lines << l }
+      lines << :footer
+      lines
+    end
+
+    def build_queue_jobs_detail(collector)
+      lines = []
+      lines << header_bar
+      lines << ""
+      stats_meters(collector.overview, collector.processes).each_line(chomp: true) { |l| lines << l }
+      lines << ""
+      max_rows = terminal_height - 12
+      jobs = collector.respond_to?(:queue_jobs_cache) ? collector.queue_jobs_cache : []
+      queue_jobs_selectable(jobs, max_rows).each_line(chomp: true) { |l| lines << l }
       lines << :footer
       lines
     end
@@ -254,7 +378,9 @@ module Sktop
       lines = []
       lines << header_bar
       lines << ""
-      max_rows = terminal_height - 5
+      stats_meters(collector.overview, collector.processes).each_line(chomp: true) { |l| lines << l }
+      lines << ""
+      max_rows = terminal_height - 12
       processes_selectable(collector.processes, max_rows).each_line(chomp: true) { |l| lines << l }
       lines << :footer
       lines
@@ -264,7 +390,9 @@ module Sktop
       lines = []
       lines << header_bar
       lines << ""
-      max_rows = terminal_height - 5
+      stats_meters(collector.overview, collector.processes).each_line(chomp: true) { |l| lines << l }
+      lines << ""
+      max_rows = terminal_height - 12
       workers_section(collector.workers, max_rows: max_rows, scrollable: true).each_line(chomp: true) { |l| lines << l }
       lines << :footer
       lines
@@ -274,7 +402,9 @@ module Sktop
       lines = []
       lines << header_bar
       lines << ""
-      max_rows = terminal_height - 5
+      stats_meters(collector.overview, collector.processes).each_line(chomp: true) { |l| lines << l }
+      lines << ""
+      max_rows = terminal_height - 12
       retries_scrollable(collector.retry_jobs(limit: 500), max_rows).each_line(chomp: true) { |l| lines << l }
       lines << :footer
       lines
@@ -284,7 +414,9 @@ module Sktop
       lines = []
       lines << header_bar
       lines << ""
-      max_rows = terminal_height - 5
+      stats_meters(collector.overview, collector.processes).each_line(chomp: true) { |l| lines << l }
+      lines << ""
+      max_rows = terminal_height - 12
       scheduled_scrollable(collector.scheduled_jobs(limit: 500), max_rows).each_line(chomp: true) { |l| lines << l }
       lines << :footer
       lines
@@ -294,7 +426,9 @@ module Sktop
       lines = []
       lines << header_bar
       lines << ""
-      max_rows = terminal_height - 5
+      stats_meters(collector.overview, collector.processes).each_line(chomp: true) { |l| lines << l }
+      lines << ""
+      max_rows = terminal_height - 12
       dead_scrollable(collector.dead_jobs(limit: 500), max_rows).each_line(chomp: true) { |l| lines << l }
       lines << :footer
       lines
@@ -601,6 +735,133 @@ module Sktop
       lines.join("\n")
     end
 
+    # Selectable queues view - press Enter to view queue contents
+    def queues_selectable(queues, max_rows)
+      width = terminal_width
+      lines = []
+
+      scroll_offset = @scroll_offsets[@current_view]
+      data_rows = max_rows - 3  # Account for section bar, header, and status line
+      max_scroll = [queues.length - data_rows, 0].max
+      scroll_offset = [[scroll_offset, 0].max, max_scroll].min
+      @scroll_offsets[@current_view] = scroll_offset
+
+      # Clamp selected index
+      @selected_index[@current_view] = [[@selected_index[@current_view], 0].max, [queues.length - 1, 0].max].min
+
+      # Auto-scroll to keep selection visible
+      selected = @selected_index[@current_view]
+      if selected < scroll_offset
+        scroll_offset = selected
+        @scroll_offsets[@current_view] = scroll_offset
+      elsif selected >= scroll_offset + data_rows
+        scroll_offset = selected - data_rows + 1
+        @scroll_offsets[@current_view] = scroll_offset
+      end
+
+      scroll_indicator = queues.length > data_rows ? " [#{scroll_offset + 1}-#{[scroll_offset + data_rows, queues.length].min}/#{queues.length}]" : ""
+      lines << section_bar("Queues#{scroll_indicator} - ↑↓ select, Enter=view jobs, m=main")
+
+      if queues.empty?
+        lines << @pastel.dim("  No queues")
+        return lines.join("\n")
+      end
+
+      name_width = [40, width - 40].max
+      header = sprintf("  %-#{name_width}s %10s %10s %10s", "NAME", "SIZE", "LATENCY", "STATUS")
+      lines << format_table_header(header)
+
+      queues.drop(scroll_offset).first(data_rows).each_with_index do |queue, idx|
+        actual_idx = scroll_offset + idx
+        row = format_queue_row(queue, name_width)
+
+        if actual_idx == selected
+          lines << @pastel.black.on_white(row + " " * [width - visible_string_length(row), 0].max)
+        else
+          lines << row
+        end
+      end
+
+      remaining = queues.length - scroll_offset - data_rows
+      if remaining > 0
+        lines << @pastel.dim("  ↓ #{remaining} more")
+      end
+
+      # Status message
+      if @status_message && @status_time && (Time.now - @status_time) < 3
+        lines << @pastel.green("  #{@status_message}")
+      end
+
+      lines.join("\n")
+    end
+
+    # Selectable queue jobs view - press Ctrl+X to delete job
+    def queue_jobs_selectable(jobs, max_rows)
+      width = terminal_width
+      lines = []
+
+      scroll_offset = @scroll_offsets[@current_view]
+      data_rows = max_rows - 3  # Account for section bar, header, and status line
+      max_scroll = [jobs.length - data_rows, 0].max
+      scroll_offset = [[scroll_offset, 0].max, max_scroll].min
+      @scroll_offsets[@current_view] = scroll_offset
+
+      # Clamp selected index
+      @selected_index[@current_view] = [[@selected_index[@current_view], 0].max, [jobs.length - 1, 0].max].min
+
+      # Auto-scroll to keep selection visible
+      selected = @selected_index[@current_view]
+      if selected < scroll_offset
+        scroll_offset = selected
+        @scroll_offsets[@current_view] = scroll_offset
+      elsif selected >= scroll_offset + data_rows
+        scroll_offset = selected - data_rows + 1
+        @scroll_offsets[@current_view] = scroll_offset
+      end
+
+      queue_name = @selected_queue || "unknown"
+      scroll_indicator = jobs.length > data_rows ? " [#{scroll_offset + 1}-#{[scroll_offset + data_rows, jobs.length].min}/#{jobs.length}]" : ""
+      lines << section_bar("Queue: #{queue_name}#{scroll_indicator} - ↑↓ select, ^X=delete, Esc=back")
+
+      if jobs.empty?
+        lines << @pastel.dim("  No jobs in queue")
+        return lines.join("\n")
+      end
+
+      job_width = [35, (width - 50) / 2].max
+      args_width = [35, (width - 50) / 2].max
+
+      header = sprintf("  %-#{job_width}s %-20s %-#{args_width}s", "JOB", "ENQUEUED", "ARGS")
+      lines << format_table_header(header)
+
+      jobs.drop(scroll_offset).first(data_rows).each_with_index do |job, idx|
+        actual_idx = scroll_offset + idx
+        klass = truncate(job[:class].to_s, job_width)
+        enqueued = job[:enqueued_at]&.strftime("%Y-%m-%d %H:%M:%S") || "N/A"
+        args = truncate(job[:args].inspect, args_width)
+
+        row = sprintf("  %-#{job_width}s %-20s %-#{args_width}s", klass, enqueued, args)
+
+        if actual_idx == selected
+          lines << @pastel.black.on_white(row + " " * [width - visible_string_length(row), 0].max)
+        else
+          lines << row
+        end
+      end
+
+      remaining = jobs.length - scroll_offset - data_rows
+      if remaining > 0
+        lines << @pastel.dim("  ↓ #{remaining} more")
+      end
+
+      # Status message
+      if @status_message && @status_time && (Time.now - @status_time) < 3
+        lines << @pastel.green("  #{@status_message}")
+      end
+
+      lines.join("\n")
+    end
+
     def format_queue_row(queue, name_width)
       name = truncate(queue[:name], name_width)
       size = format_number(queue[:size])
@@ -1083,31 +1344,36 @@ module Sktop
     end
 
     def function_bar
-      items = if @current_view == :main
-        [
-          ["q", "Queues"],
-          ["p", "Procs"],
-          ["w", "Workers"],
-          ["r", "Retries"],
-          ["s", "Sched"],
-          ["d", "Dead"],
-          ["^C", "Quit"]
-        ]
-      else
-        [
-          ["m", "Main"],
-          ["q", "Queues"],
-          ["p", "Procs"],
-          ["w", "Workers"],
-          ["r", "Retries"],
-          ["s", "Sched"],
-          ["d", "Dead"],
-          ["^C", "Quit"]
-        ]
-      end
+      # Map keys to views for highlighting
+      view_keys = {
+        "m" => :main,
+        "q" => :queues,
+        "p" => :processes,
+        "w" => :workers,
+        "r" => :retries,
+        "s" => :scheduled,
+        "d" => :dead
+      }
+
+      items = [
+        ["m", "Main"],
+        ["q", "Queues"],
+        ["p", "Procs"],
+        ["w", "Workers"],
+        ["r", "Retries"],
+        ["s", "Sched"],
+        ["d", "Dead"],
+        ["^C", "Quit"]
+      ]
 
       bar = items.map do |key, label|
-        @pastel.black.on_cyan.bold(key) + @pastel.white.on_blue(label)
+        view = view_keys[key]
+        if view && view == @current_view
+          # Highlight current view with inverted colors
+          @pastel.black.on_white.bold(key) + @pastel.black.on_green.bold(label)
+        else
+          @pastel.black.on_cyan.bold(key) + @pastel.white.on_blue(label)
+        end
       end.join(" ")
 
       width = terminal_width

data/lib/sktop/job_actions.rb

@@ -1,8 +1,28 @@
 # frozen_string_literal: true
 
 module Sktop
+  # Provides methods for performing actions on Sidekiq jobs and processes.
+  # All methods are class methods and can be called directly on the module.
+  #
+  # @example Retry a failed job
+  #   Sktop::JobActions.retry_job("abc123", :retry)
+  #
+  # @example Delete a dead job
+  #   Sktop::JobActions.delete_job("abc123", :dead)
+  #
+  # @example Quiet a Sidekiq process
+  #   Sktop::JobActions.quiet_process("myhost:12345:abc")
   module JobActions
     class << self
+      # Retry a specific job from the retry or dead queue.
+      #
+      # @param jid [String] the job ID to retry
+      # @param source [Symbol] the source queue (:retry or :dead)
+      # @return [Boolean] true if the job was successfully retried
+      # @raise [RuntimeError] if the job is not found
+      #
+      # @example Retry a job from the retry queue
+      #   Sktop::JobActions.retry_job("abc123def456", :retry)
       def retry_job(jid, source)
         job = find_job(jid, source)
         raise "Job not found (JID: #{jid})" unless job
@@ -11,6 +31,12 @@ module Sktop
         true
       end
 
+      # Delete a specific job from the retry or dead queue.
+      #
+      # @param jid [String] the job ID to delete
+      # @param source [Symbol] the source queue (:retry or :dead)
+      # @return [Boolean] true if the job was successfully deleted
+      # @raise [RuntimeError] if the job is not found
       def delete_job(jid, source)
         job = find_job(jid, source)
         raise "Job not found (JID: #{jid})" unless job
@@ -19,6 +45,12 @@ module Sktop
         true
       end
 
+      # Kill a specific job, moving it to the dead queue.
+      #
+      # @param jid [String] the job ID to kill
+      # @param source [Symbol] the source queue (:retry or :scheduled)
+      # @return [Boolean] true if the job was successfully killed
+      # @raise [RuntimeError] if the job is not found
       def kill_job(jid, source)
         job = find_job(jid, source)
         raise "Job not found (JID: #{jid})" unless job
@@ -27,6 +59,10 @@ module Sktop
         true
       end
 
+      # Retry all jobs in a sorted set (retry or dead queue).
+      #
+      # @param source [Symbol] the source queue (:retry or :dead)
+      # @return [Integer] the number of jobs retried
       def retry_all(source)
         set = get_set(source)
         count = set.size
@@ -34,6 +70,10 @@ module Sktop
         count
       end
 
+      # Delete all jobs from a sorted set (retry or dead queue).
+      #
+      # @param source [Symbol] the source queue (:retry or :dead)
+      # @return [Integer] the number of jobs deleted
       def delete_all(source)
         set = get_set(source)
         count = set.size
@@ -41,6 +81,27 @@ module Sktop
         count
       end
 
+      # Delete a specific job from a named queue.
+      #
+      # @param queue_name [String] the name of the queue
+      # @param jid [String] the job ID to delete
+      # @return [Boolean] true if the job was successfully deleted
+      # @raise [RuntimeError] if the job is not found in the queue
+      def delete_queue_job(queue_name, jid)
+        queue = Sidekiq::Queue.new(queue_name)
+        job = queue.find { |j| j.jid == jid }
+        raise "Job not found in queue #{queue_name} (JID: #{jid})" unless job
+
+        job.delete
+        true
+      end
+
+      # Send the QUIET signal to a Sidekiq process.
+      # A quieted process stops fetching new jobs but finishes current work.
+      #
+      # @param identity [String] the process identity (e.g., "hostname:pid:tag")
+      # @return [Boolean] true if the signal was sent successfully
+      # @raise [RuntimeError] if the process is not found
       def quiet_process(identity)
         process = find_process(identity)
         raise "Process not found (identity: #{identity})" unless process
@@ -49,6 +110,12 @@ module Sktop
         true
       end
 
+      # Send the STOP signal to a Sidekiq process.
+      # This initiates a graceful shutdown of the process.
+      #
+      # @param identity [String] the process identity (e.g., "hostname:pid:tag")
+      # @return [Boolean] true if the signal was sent successfully
+      # @raise [RuntimeError] if the process is not found
       def stop_process(identity)
         process = find_process(identity)
         raise "Process not found (identity: #{identity})" unless process
@@ -59,6 +126,12 @@ module Sktop
 
       private
 
+      # Get the appropriate Sidekiq sorted set for a given source.
+      #
+      # @param source [Symbol] the source type (:retry, :dead, or :scheduled)
+      # @return [Sidekiq::RetrySet, Sidekiq::DeadSet, Sidekiq::ScheduledSet]
+      # @raise [RuntimeError] if the source is unknown
+      # @api private
       def get_set(source)
         case source
         when :retry
@@ -72,6 +145,12 @@ module Sktop
         end
       end
 
+      # Find a job by JID in a sorted set.
+      #
+      # @param jid [String] the job ID to find
+      # @param source [Symbol] the source type (:retry, :dead, or :scheduled)
+      # @return [Sidekiq::SortedEntry, nil] the job entry or nil if not found
+      # @api private
       def find_job(jid, source)
         set = get_set(source)
 
@@ -89,6 +168,11 @@ module Sktop
         nil
       end
 
+      # Find a Sidekiq process by its identity string.
+      #
+      # @param identity [String] the process identity
+      # @return [Sidekiq::Process, nil] the process or nil if not found
+      # @api private
       def find_process(identity)
         Sidekiq::ProcessSet.new.find { |p| p["identity"] == identity }
       end

data/lib/sktop/stats_collector.rb

@@ -1,16 +1,48 @@
 # frozen_string_literal: true
 
 module Sktop
+  # Collects statistics and data from Sidekiq for display in the TUI.
+  # Wraps the Sidekiq API to provide a consistent interface for querying
+  # queues, processes, workers, and job data.
+  #
+  # @example Basic usage
+  #   collector = Sktop::StatsCollector.new
+  #   puts collector.overview[:processed]
+  #   puts collector.queues.length
+  #
+  # @example Refreshing data
+  #   collector = Sktop::StatsCollector.new
+  #   loop do
+  #     collector.refresh!
+  #     display_stats(collector.overview)
+  #     sleep 2
+  #   end
   class StatsCollector
+    # Create a new StatsCollector instance.
+    # Initializes with fresh statistics from Sidekiq.
     def initialize
       @stats = Sidekiq::Stats.new
     end
 
+    # Refresh the cached statistics from Sidekiq.
+    # Call this method periodically to get updated data.
+    #
+    # @return [self] the collector instance for method chaining
     def refresh!
       @stats = Sidekiq::Stats.new
       self
     end
 
+    # Get an overview of Sidekiq statistics.
+    #
+    # @return [Hash] overview statistics
+    # @option return [Integer] :processed total jobs processed
+    # @option return [Integer] :failed total jobs failed
+    # @option return [Integer] :scheduled_size jobs in scheduled queue
+    # @option return [Integer] :retry_size jobs in retry queue
+    # @option return [Integer] :dead_size jobs in dead queue
+    # @option return [Integer] :enqueued total jobs across all queues
+    # @option return [Float] :default_queue_latency latency of default queue in seconds
     def overview
       {
         processed: @stats.processed,
@@ -23,6 +55,13 @@ module Sktop
       }
     end
 
+    # Get information about all Sidekiq queues.
+    #
+    # @return [Array<Hash>] array of queue information hashes
+    # @option return [String] :name queue name
+    # @option return [Integer] :size number of jobs in queue
+    # @option return [Float] :latency queue latency in seconds
+    # @option return [Boolean] :paused whether the queue is paused
     def queues
       Sidekiq::Queue.all.map do |queue|
         {
@@ -34,6 +73,21 @@ module Sktop
       end
     end
 
+    # Get information about all running Sidekiq processes.
+    #
+    # @return [Array<Hash>] array of process information hashes
+    # @option return [String] :identity unique process identifier
+    # @option return [String] :hostname the host running the process
+    # @option return [Integer] :pid process ID
+    # @option return [String, nil] :tag optional process tag
+    # @option return [Time] :started_at when the process started
+    # @option return [Integer] :concurrency number of worker threads
+    # @option return [Integer] :busy number of threads currently processing
+    # @option return [Array<String>] :queues queues this process listens to
+    # @option return [Array<String>] :labels process labels
+    # @option return [Boolean] :quiet whether the process is quieted
+    # @option return [Boolean] :stopping whether the process is stopping
+    # @option return [Integer, nil] :rss memory usage in KB
     def processes
       Sidekiq::ProcessSet.new.map do |process|
         # Use direct hash access for status flags - the method accessors
@@ -61,12 +115,30 @@ module Sktop
       end
     end
 
+    # Get information about all currently running workers.
+    #
+    # @return [Array<Hash>] array of worker information hashes
+    # @option return [String] :process_id the process identity
+    # @option return [String] :thread_id the thread identifier
+    # @option return [String] :queue the queue being processed
+    # @option return [String] :class the job class name
+    # @option return [Array] :args the job arguments
+    # @option return [Time] :run_at when the job started
+    # @option return [Float] :elapsed seconds since job started
     def workers
       Sidekiq::Workers.new.map do |process_id, thread_id, work|
         extract_worker_info(process_id, thread_id, work)
       end
     end
 
+    # Extract worker information from Sidekiq's Workers API.
+    # Handles both Sidekiq 6.x (hash-based) and 7.x (Work object) formats.
+    #
+    # @param process_id [String] the process identity
+    # @param thread_id [String] the thread identifier
+    # @param work [Hash, Sidekiq::Work] the work data (format depends on Sidekiq version)
+    # @return [Hash] normalized worker information
+    # @api private
     def extract_worker_info(process_id, thread_id, work)
       # Sidekiq 7+ returns Work objects, older versions return hashes
       if work.is_a?(Hash)
@@ -108,6 +180,38 @@ module Sktop
       end
     end
 
+    # Get jobs from a specific queue.
+    #
+    # @param queue_name [String] the name of the queue
+    # @param limit [Integer] maximum number of jobs to return (default: 100)
+    # @return [Array<Hash>] array of job information hashes
+    # @option return [String] :jid the job ID
+    # @option return [String] :class the job class name
+    # @option return [Array] :args the job arguments
+    # @option return [Time, nil] :enqueued_at when the job was enqueued
+    # @option return [Time, nil] :created_at when the job was created
+    def queue_jobs(queue_name, limit: 100)
+      queue = Sidekiq::Queue.new(queue_name)
+      queue.first(limit).map do |job|
+        {
+          jid: job.jid,
+          class: job.klass,
+          args: job.args,
+          enqueued_at: job.enqueued_at,
+          created_at: job.created_at
+        }
+      end
+    end
+
+    # Get jobs from the scheduled queue.
+    #
+    # @param limit [Integer] maximum number of jobs to return (default: 10)
+    # @return [Array<Hash>] array of scheduled job information hashes
+    # @option return [String] :class the job class name
+    # @option return [String] :queue the target queue
+    # @option return [Array] :args the job arguments
+    # @option return [Time] :scheduled_at when the job is scheduled to run
+    # @option return [Time, nil] :created_at when the job was created
     def scheduled_jobs(limit: 10)
       Sidekiq::ScheduledSet.new.first(limit).map do |job|
         {
@@ -120,6 +224,18 @@ module Sktop
       end
     end
 
+    # Get jobs from the retry queue.
+    #
+    # @param limit [Integer] maximum number of jobs to return (default: 10)
+    # @return [Array<Hash>] array of retry job information hashes
+    # @option return [String] :jid the job ID
+    # @option return [String] :class the job class name
+    # @option return [String] :queue the original queue
+    # @option return [Array] :args the job arguments
+    # @option return [Time, nil] :failed_at when the job failed
+    # @option return [Integer] :retry_count number of retry attempts
+    # @option return [String] :error_class the exception class name
+    # @option return [String] :error_message the exception message
     def retry_jobs(limit: 10)
       Sidekiq::RetrySet.new.first(limit).map do |job|
         {
@@ -135,6 +251,17 @@ module Sktop
       end
     end
 
+    # Get jobs from the dead (morgue) queue.
+    #
+    # @param limit [Integer] maximum number of jobs to return (default: 10)
+    # @return [Array<Hash>] array of dead job information hashes
+    # @option return [String] :jid the job ID
+    # @option return [String] :class the job class name
+    # @option return [String] :queue the original queue
+    # @option return [Array] :args the job arguments
+    # @option return [Time, nil] :failed_at when the job failed
+    # @option return [String] :error_class the exception class name
+    # @option return [String] :error_message the exception message
     def dead_jobs(limit: 10)
       Sidekiq::DeadSet.new.first(limit).map do |job|
         {
@@ -149,6 +276,12 @@ module Sktop
       end
     end
 
+    # Get historical statistics for processed and failed jobs.
+    #
+    # @param days [Integer] number of days of history to retrieve (default: 7)
+    # @return [Hash] history data
+    # @option return [Hash] :processed daily processed counts keyed by date
+    # @option return [Hash] :failed daily failed counts keyed by date
     def history(days: 7)
       stats_history = Sidekiq::Stats::History.new(days)
       {

data/lib/sktop/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 module Sktop
-  VERSION = "0.1.5"
+  # Current version of the Sktop gem.
+  # Follows semantic versioning (major.minor.patch).
+  # @return [String] the version string
+  VERSION = "0.2.0"
 end

data/lib/sktop.rb

@@ -13,10 +13,31 @@ require_relative "sktop/job_actions"
 require_relative "sktop/display"
 require_relative "sktop/cli"
 
+# Sktop is a terminal-based Sidekiq monitoring tool similar to htop.
+# It provides real-time visibility into Sidekiq processes, queues,
+# workers, and job status with an interactive TUI.
+#
+# @example Running from command line
+#   sktop -r redis://localhost:6379/0
+#
+# @example Using in Ruby code
+#   Sktop.configure_redis(url: "redis://localhost:6379/0")
+#   Sktop::CLI.new.run
+#
+# @see https://github.com/jamez01/sktop
 module Sktop
+  # Base error class for all Sktop errors
   class Error < StandardError; end
 
   class << self
+    # Configure the Redis connection for Sidekiq client mode.
+    #
+    # @param url [String, nil] Redis connection URL (e.g., "redis://localhost:6379/0")
+    # @param namespace [String, nil] Redis namespace for Sidekiq keys (currently unused)
+    # @return [void]
+    #
+    # @example Configure with a custom Redis URL
+    #   Sktop.configure_redis(url: "redis://myredis:6379/1")
     def configure_redis(url: nil, namespace: nil)
       options = {}
       options[:url] = url if url

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sktop
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.0
 platform: ruby
 authors:
 - James
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-17 00:00:00.000000000 Z
+date: 2026-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sidekiq