sktop 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72e27a287d42246bf03393f3f5d8fd83fcf2dcb52d3c32a242f6631a556d5a90
-  data.tar.gz: a26fa56421cf3fa038f2d7fa7ec86e204189be4bd21419d1ddf896631f59a8cc
+  metadata.gz: d1e0891fc2a69763f5784c7cc96fc69103d14362aa67a08b82b6c13aa578985b
+  data.tar.gz: fea7b7284c37d666516d42c2bcc97e0f6b3db4cbb53628e2e3b35c6521c44845
 SHA512:
-  metadata.gz: d7aa57eac65085688adadc80a4d587c6c3e0c100c09518675bf4cc65fdcfac93e37e404a7476eda3a4b4ec2d2b7a595f3e6231a2b1c414475c4907fd52ff4275
-  data.tar.gz: ef09ee20ae517a01e85c427bc291d8adff140e0239342336f22365df774efdf83c0df76b34839ed99e15d63a66c36de4eaeb4f7634a24d098c27fab6894055ec
+  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
@@ -267,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
@@ -276,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'
@@ -336,6 +377,10 @@ module Sktop
       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)
 
@@ -375,6 +420,10 @@ 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
@@ -420,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)
 
@@ -433,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)
 
@@ -446,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
 
@@ -483,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
 
@@ -520,6 +585,10 @@ 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
 
@@ -563,6 +632,10 @@ module Sktop
       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
@@ -574,6 +647,10 @@ module Sktop
       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/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
@@ -18,16 +33,23 @@ module Sktop
       @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
@@ -36,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
@@ -44,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?
       [: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?
@@ -57,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?
@@ -66,51 +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
@@ -120,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
@@ -138,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
@@ -149,40 +219,58 @@ 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
@@ -264,8 +352,10 @@ 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
+      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
@@ -275,7 +365,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
       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
@@ -286,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
@@ -296,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
@@ -306,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
@@ -316,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
@@ -326,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

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,12 @@ 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 }
@@ -50,6 +96,12 @@ module Sktop
         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
@@ -58,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
@@ -68,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
@@ -81,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)
 
@@ -98,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,16 @@ 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|
@@ -121,6 +203,15 @@ module Sktop
       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|
         {
@@ -133,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|
         {
@@ -148,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|
         {
@@ -162,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.6"
+  # 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.6
+  version: 0.2.0
 platform: ruby
 authors:
 - James
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-18 00:00:00.000000000 Z
+date: 2026-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sidekiq