utils 0.81.0 → 0.83.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f4a74cb28195b08e8c1105b16b40a4d79189c4e8a5396a1f2df3deba71ed9d4
-  data.tar.gz: 4d01dc2e96f809e5ed338f875f87e90468721b190bb79856aa854830a4b413bf
+  metadata.gz: feae6a2fca0157be211250ec430f5f21a1c155653ace2c13b40ac20b281eca09
+  data.tar.gz: 9a5e7c3a34a1ead5023dde6b152d6d94a2f596a75405615fe109a931807a8b29
 SHA512:
-  metadata.gz: 12e0c3edbef1d6ce684ea79bb80ac0379f5962626d07cc574906df58bd2158225c4732982850c6adefd0dbb4cd7347eff58f7f3422537bb96da57ac5f62ec5bd
-  data.tar.gz: cd3eddebabc474a530dfca7427bda4dffbbf377a09bf8b891d6c8ef51c2fc2aa033c625254ea88854d0b3b8e83207e59097276ccf06840c461c23fd872929995
+  metadata.gz: 2038fbdb9eb1822f8b095fba1620f90ddfdd71220496fd8c25a8b4a51d50c535a77fde0f6b4433bd0eca2101753cd54c4dc266644f7235736333b8f1e6f43201
+  data.tar.gz: 9cdff942de8097052d296f06bdc8e5f7a75572a8ccd2c63831a37248a6b9d1f0f99f0d92c400b1888e3007eb40816c2b1ee2e0a37ea0852b6e10de3bd1d16b28

data/bin/code_comment

@@ -184,7 +184,7 @@ end
 filename_linenumber = ARGV.shift or fail "require file_name as second argument"
 $config = Utils::ConfigFile.new
 $config.configure_from_paths
-$config_dir             = Utils::ConfigDir.new('code_comment', env_var: 'XDG_CONFIG_HOME')
+$config_dir         = Utils::ConfigDir.new('code_comment', env_var: 'XDG_CONFIG_HOME')
 base_url            = ENV['OLLAMA_URL'] || 'http://%s' % ENV.fetch('OLLAMA_HOST')
 model               = ENV.fetch('OLLAMA_MODEL', 'llama3.1')
 construct, construct_type = fetch_construct(filename_linenumber)

data/bin/irb_client

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+
+require 'utils/irb'
+include Utils::IRB
+
+def usage
+  <<~EOT
+    Usage: #{File.basename($0)} ACTION
+
+    Actions:
+      store_snippet            Store code snippet from STDIN as current snippet
+      retrieve_current_snippet Show the currently stored snippet
+      eval_current_snippet     Evaluate the currently stored snippet
+      execute_current_snippet  Execute the currently stored snippet (no output)
+      execute_snippet          Execute code snippet from STDIN (no output)
+      eval_snippet             Evaluate code snippet from STDIN and print result
+      eval_lines               Evaluate code lines from STDIND and print comment results
+      stop_server              Stop the IRB server
+
+    Examples:
+      # Evaluate code and get result
+      echo '2 + 2' | #{File.basename($0)} eval_snippet
+      # => 4
+
+      # Execute code (no output)
+      echo 'puts "hello"' | #{File.basename($0)} execute_snippet
+
+      # Store code snippet
+      echo 'def hello; "world"; end' | #{File.basename($0)} store_snippet
+
+      # Work with stored snippets
+      echo 'def hello; "world"; end' | #{File.basename($0)} store_snippet
+      #{File.basename($0)} retrieve_current_snippet
+      # => def hello; "world"; end
+      #{File.basename($0)} eval_current_snippet
+      # => "world"
+
+      # Stop server
+      #{File.basename($0)} stop_server
+  EOT
+end
+    
+case action = ARGV.shift || 'usage'
+when 'store_snippet'
+  irb_client.send(action, STDIN.read)
+when 'retrieve_current_snippet'
+  puts irb_client.send('eval_snippet', '@snippet')
+when 'eval_current_snippet'
+  puts irb_client.send('eval_snippet', 'eval(@snippet)')
+when 'execute_current_snippet'
+  puts irb_client.send('execute_snippet', 'eval(@snippet)')
+when 'execute_snippet'
+  irb_client.send(action, STDIN.read)
+when 'eval_snippet'
+  puts irb_client.send(action, STDIN.read)
+when 'eval_lines'
+  prefix = ARGV.shift || ' # => '
+  lines  = STDIN.readlines
+  if lines.empty?
+    abort "No input provided"
+  else
+    puts irb_client.send('eval_lines', lines, prefix)
+  end
+when 'stop_server'
+  irb_client.send(action)
+else
+  abort usage
+end

data/bin/probe

@@ -14,6 +14,7 @@
 
 require 'utils'
 include Utils
+include Utils::Probe
 include Tins::GO
 require 'shellwords'
 
@@ -78,7 +79,7 @@ end
 # probe server instance to handle incoming requests and process jobs.
 def start_server
   Thread.abort_on_exception = $DEBUG
-  Utils::ProbeServer.new(
+  ProbeServer.new(
     server_type: $config.probe.server_type,
     port: $config.probe.tcp_server_port
   ).start
@@ -92,7 +93,7 @@ end
 # It also enqueues jobs for execution on the probe server when specified.
 #
 def connect_server
-  probe_client = Utils::ProbeClient.new(
+  probe_client = ProbeClient.new(
     server_type: $config.probe.server_type,
     port: $config.probe.tcp_server_port
   )

data/lib/utils/config_file.rb

@@ -288,6 +288,17 @@ class Utils::ConfigFile
     @probe ||= Probe.new
   end
 
+  # The irb_server_url method configures the URL for the IRB server
+  # communication.
+  #
+  # This method sets up a DSL accessor for the IRB server URL, providing a
+  # default value that uses a Unix domain socket located in the current working
+  # directory.
+  #
+  # @return [ String ] the configured IRB server URL including the default
+  #   socket path
+  dsl_accessor :irb_server_url, "unix://#{Pathname.pwd + 'irb.socket'}"
+
   # A configuration class for file system operations.
   #
   # This class manages the configuration settings for searching and discovering

data/lib/utils/irb/irb_server.rb

@@ -0,0 +1,219 @@
+require 'logger'
+require 'fileutils'
+
+# A class that provides server functionality for interactive Ruby (IRB)
+# sessions.
+#
+# This class manages an IRB server instance that can receive and process code
+# snippets for evaluation. It handles communication through Unix domain
+# sockets, allowing external clients to send code for execution and receive the
+# results back.
+#
+# @example
+#   server = Utils::IRB::IRBServer.new(url: 'unix:///tmp/irb.sock')
+#   server.start
+#   #
+#   client = Utils::IRB::IRBServer.new(url: 'unix:///tmp/irb.sock')
+#   client.store_snippet('puts "Hello World"')
+#   result = server.eval_snippet('2 + 2')
+class Utils::IRB::IRBServer
+  # The initialize method sets up a new IRBServer instance with the specified
+  # URL.
+  #
+  # This method configures the IRB server by initializing a logger for error
+  # reporting and storing the provided URL for server communication.
+  #
+  # @param url [ String ] the URL to be used for the IRB server communication
+  def initialize(url:, log_out: nil)
+    @url     = url
+    @log_out = log_out
+  end
+
+  # The url reader method provides access to the URL instance variable.
+  #
+  # @return [ String ] the URL value stored in the instance variable
+  attr_reader :url
+
+  # The snippet reader method provides access to the snippet instance variable.
+  #
+  # @return [ Object ] the snippet value stored in the instance variable
+  attr_reader :snippet
+
+  # The start method initializes and begins operation of the IRB server.
+  #
+  # This method sets up the server by building the underlying socket connection,
+  # logging the start event, and configuring a background receiver to handle
+  # incoming messages. It processes different message actions such as storing
+  # code snippets or evaluating code, and responds appropriately to each
+  # message type.
+  #
+  # @return [ Utils::IRB::IRBServer ] returns self to allow for method chaining
+  def start
+    @server = build_server
+    @logger.info "Starting #{self.class.name} server on #{@url}."
+    @server.receive_in_background do |message|
+      case message.action
+      when 'store'
+        @snippet = message.snippet
+        @logger.info "Stored #{message.to_json}."
+      when 'execute'
+        time_eval { eval(message.snippet) }
+        @logger.info "Execution of #{message.to_json} took %.2fs" % @eval_duration
+      when 'eval'
+        result = time_eval { eval(message.snippet) }
+        @logger.info "Evaluation of #{message.to_json} took %.2fs" % @eval_duration
+        message.respond(result: result.to_s, type: message.action)
+      when 'eval_lines'
+        b = binding
+        result = message.lines.map do |line|
+          l = line.chomp
+          r = b.eval(l)
+          [ l, message.prefix, r ].join
+        end.join(?\n)
+        message.respond(result: result, type: message.action)
+      when 'stop'
+        @logger.info "Stopping #{self.class.name} server on #{@url}."
+        Thread.current.exit
+      else
+        @logger.warn("Message for action #{message.action.inspect} not supported.")
+      end
+    rescue => e
+      @logger.error("#{self.class.name} caught #{e.class}: #{e} for #{message.to_json}.")
+    end
+    self
+  end
+
+  # The store_snippet method transmits a code snippet to the client for storage.
+  #
+  # This method prepares a transmission request containing the specified code
+  # snippet and sends it to the client using the build_client mechanism. It is
+  # designed to facilitate the storage of code snippets within the system's
+  # communication protocol.
+  #
+  # @param code [ String ] the code snippet to be stored
+  #
+  # @return [ Utils::IRB::IRBServer ] returns self to allow for method chaining
+  def store_snippet(code)
+    build_client.transmit({ action: 'store', snippet: code })
+    self
+  end
+
+  # The execute_snippet method sends a code snippet to the IRB server for
+  # execution and waits for the response.
+  #
+  # This method transmits an execute command along with the provided code
+  # snippet to the IRB server, allowing the server to evaluate the code and
+  # return the result.
+  #
+  # @param code [ String ] the code snippet to be executed
+  #
+  # @return [ Utils::IRB::IRBServer ] returns self to allow for method chaining
+  def execute_snippet(code)
+    build_client.transmit({ action: 'execute', snippet: code })
+    self
+  end
+
+  # The eval_snippet method sends a code snippet to the IRB server for
+  # evaluation and returns the result.
+  #
+  # This method transmits the provided code snippet to the IRB server for
+  # execution, waits for the server's response, and extracts the evaluation
+  # result from the response.
+  #
+  # @param code [ String ] the code snippet to be evaluated
+  #
+  # @return [ String ] the result of the code snippet evaluation as a string
+  def eval_snippet(code)
+    message = build_client.transmit_with_response(
+      { action: 'eval', snippet: code }
+    )
+    message.result
+  end
+
+  # The eval_lines method sends a series of code lines to the IRB server for
+  # evaluation and returns the formatted results.
+  #
+  # This method transmits multiple lines of code to the IRB server for
+  # execution, with each line being evaluated in sequence. It includes a prefix
+  # for each result line and returns the combined output from the evaluation.
+  #
+  # @param lines [ Array<String> ] the array of code lines to be evaluated
+  # @param prefix [ String ] the prefix to be added to each result line, defaults to ' # => '
+  #
+  # @return [ String ] the formatted results from evaluating the code lines
+  def eval_lines(lines, prefix = ' # => ')
+    message = build_client.transmit_with_response(
+      { action: 'eval_lines', prefix:, lines: }
+    )
+    message.result
+  end
+
+  # The stop_server method sends a stop command to the IRB server.
+  #
+  # This method communicates with the IRB server to request a graceful shutdown
+  # of the server process by transmitting a stop action.
+  #
+  # @return [ nil ] always returns nil after sending the stop command
+  def stop_server
+    build_client.transmit({ action: 'stop' })
+    nil
+  end
+
+  private
+
+  # The setup_logger method configures the log output destination for the IRB
+  # server.
+  #
+  # This method determines whether a log output path has been provided, and if
+  # not, constructs a default log path using the XDG state home directory or a
+  # fallback to the user's local state directory. It ensures the log directory
+  # exists and creates a new log file for writing.
+  #
+  # @return [ String ] the path to the log file that will be used for logging
+  def setup_logger
+    unless @log_out
+      xdg_dir  = File.expand_path(ENV.fetch('XDG_STATE_HOME', '~/.local/state'))
+      log_path = Pathname.new(xdg_dir) + 'utils'
+      FileUtils.mkdir_p log_path
+      log_path += 'irb-server.log'
+      @log_out = File.new(log_path, ?a)
+    end
+    @log_out.sync = true
+    @logger = Logger.new(@log_out)
+  end
+
+  # The build_server method creates and returns a Unix domain socket server
+  # instance based on the URL configuration
+  #
+  # This method initializes a socket server by delegating to the
+  # UnixSocks.from_url factory method, which constructs an appropriate server
+  # type (TCP or domain socket) based on the URL scheme and configuration
+  # parameters
+  #
+  # @return [ UnixSocks::TCPSocketServer, UnixSocks::DomainSocketServer ] a new
+  #   socket server instance configured according to the URL specification
+  def build_server
+    setup_logger
+    UnixSocks.from_url(url)
+  end
+
+  alias build_client build_server
+
+  # The time_eval method measures the execution duration of a block.
+  #
+  # This method records the start time before yielding to the provided block,
+  # then calculates the elapsed time after the block completes, storing the
+  # duration in an instance variable for later access.
+  #
+  # @param block [ Proc ] the block of code to measure execution time for
+  #
+  # @return [ Object ] the result of the block execution
+  #
+  # @api private
+  def time_eval(&block)
+    s = Time.now
+    block.()
+  ensure
+    @eval_duration = Time.now - s
+  end
+end

data/lib/utils/irb.rb

@@ -2,6 +2,7 @@ require 'irb/completion'
 require 'enumerator'
 require 'tempfile'
 require 'pp'
+require 'shellwords'
 require 'utils'
 require_maybe 'ap'
 
@@ -83,6 +84,48 @@ module Utils
         ri(*patterns, doc: 'yri')
       end
 
+      # The ai method interacts with an Ollama chat service to process queries
+      # and optionally return responses.
+      #
+      # This method constructs command-line arguments for the ollama_chat_send
+      # utility based on the provided options, executes the command with the
+      # query as input, and returns the response if requested.
+      #
+      # @param query [ String ] the input query to send to the Ollama chat
+      #   service
+      # @param command [ TrueClass, FalseClass ] whether to treat the query as
+      #   a command
+      # @param respond [ TrueClass, FalseClass ] whether to capture and return
+      #   the response from the service
+      # @param parse [ TrueClass, FalseClass ] whether to parse the response
+      # @param dir [ String ] the directory to use for the operation
+      #
+      # @return [ String, nil ] the response from the Ollama chat service if
+      #   respond is true, otherwise nil
+      def ai(query, command: false, respond: false, parse: false, dir: ?.)
+        dir = File.expand_path(dir)
+        args = {
+          ?r => respond,
+          ?t => command,
+          ?p => parse,
+          ?d => dir,
+        }
+        args = args.map { |k, v|
+          v == false and next
+          v == true ? "-#{k}" : [ "-#{k}", v.to_s ]
+        }.flatten.compact
+        args.unshift 'ollama_chat_send'
+        response = nil
+        IO.popen(Shellwords.join(args), 'r+') do |io|
+          io.write query
+          io.close_write
+          if respond
+            response = io.read
+          end
+        end
+        response
+      end
+
       # The irb_open method opens a URL or executes a block to capture output
       # and open it.
       #
@@ -661,6 +704,50 @@ module Utils
         nil
       end
 
+      # The irb_server method provides access to an IRB server instance for
+      # interactive Ruby sessions.
+      #
+      # This method ensures that a single IRB server instance is created and
+      # started for the current process, loading the configuration from
+      # standard paths and using the configured server URL.
+      #
+      # @return [ Utils::IRB::IRBServer ] the IRB server instance, initialized
+      #   and started if not already running
+      def irb_server
+        unless @irb_server
+          config = Utils::ConfigFile.new.tap(&:configure_from_paths)
+          @irb_server = Utils::IRB::IRBServer.new(url: config.irb_server_url).start
+        end
+        @irb_server
+      end
+
+      # The irb_server_stop method sends a stop command to the IRB server
+      # client.
+      #
+      # This method accesses the IRB client instance and invokes the
+      # stop_server method on it, which gracefully shuts down the IRB server
+      # process.
+      #
+      # @return [ nil ] always returns nil after sending the stop command to
+      #   the server
+      def irb_server_stop
+        irb_client.stop_server
+      end
+
+      # The irb_client method provides access to an IRB server client instance.
+      #
+      # This method creates and returns a new IRB server client by first
+      # loading the configuration from standard paths and then using the
+      # configured server URL
+      # to initialize the client.
+      #
+      # @return [ Utils::IRB::IRBServer ] a new IRB server client instance configured
+      #         with the URL from the application's configuration
+      def irb_client
+        config = Utils::ConfigFile.new.tap(&:configure_from_paths)
+        Utils::IRB::IRBServer.new(url: config.irb_server_url)
+      end
+
       # The ed method opens files for editing using the system editor.
       #
       # This method provides a convenient way to edit files by invoking the
@@ -794,6 +881,8 @@ module Utils
   end
 end
 
+require 'utils/irb/irb_server'
+
 Utils::IRB.configure
 
 class String

data/lib/utils/probe/probe_client.rb

@@ -0,0 +1,98 @@
+module Utils::Probe
+  # A client for interacting with the probe server through Unix domain sockets.
+  #
+  # This class provides an interface for enqueueing process jobs and managing
+  # environment variables on a remote probe server. It uses Unix domain sockets
+  # to communicate with the server, enabling distributed task execution and
+  # configuration management.
+  class ProbeClient
+    include ServerHandling
+
+    # A proxy class for managing environment variables through a probe server communication channel.
+    #
+    # This class provides a wrapper around the ENV object that allows setting and retrieving
+    # environment variables while logging these operations through the probe server.
+    # It intercepts assignments and lookups to provide visibility into environment modifications
+    # during probe server operations.
+    class EnvProxy
+      # The initialize method sets up a new instance with the provided server
+      # object.
+      #
+      # @param server [ UnixSocks::Server ] the server object to be assigned
+      # to the instance variable
+      def initialize(server)
+        @server = server
+      end
+
+      # The []= method sets an environment variable value through the probe server.
+      #
+      # This method transmits a request to the probe server to set the specified
+      # environment variable key to the given value, then returns the updated
+      # environment value from the server's response.
+      #
+      # @param key [ String ] the environment variable key to set
+      # @param value [ String ] the value to assign to the environment variable
+      #
+      # @return [ String ] the updated environment variable value returned by the server
+      def []=(key, value)
+        response = @server.transmit_with_response(type: 'set_env', key:, value:)
+        response.env
+      end
+
+      # The [] method retrieves the value of an environment variable from the probe server.
+      #
+      # This method sends a request to the probe server to fetch the current value of the specified
+      # environment variable key and returns the corresponding value.
+      #
+      # @param key [ String ] the environment variable key to retrieve
+      #
+      # @return [ String ] the value of the specified environment variable
+      def [](key)
+        response = @server.transmit_with_response(type: 'get_env', key:)
+        response.env
+      end
+
+      attr_reader :env
+    end
+
+    # The initialize method sets up a new probe server instance.
+    #
+    # This method creates and configures a Unix domain socket server for
+    # handling probe jobs and communication. It initializes the server with a
+    # specific socket name and runtime directory, preparing it to listen for
+    # incoming connections and process jobs.
+    #
+    # @return [ Utils::ProbeServer ] a new probe server instance configured with
+    #         the specified socket name and runtime directory
+    def initialize(server_type: :unix, port: 6666)
+      @server = create_server(server_type, port)
+    end
+
+    # The env method provides access to environment variable management through
+    # a proxy object.
+    #
+    # This method returns an EnvProxy instance that allows for setting and
+    # retrieving environment variables via the probe server communication
+    # channel.
+    #
+    # @return [ Utils::ProbeServer::EnvProxy ] a proxy object for environment
+    # variable operations
+    def env
+      EnvProxy.new(@server)
+    end
+
+    # The enqueue method submits a new process job to the probe server for
+    # execution.
+    #
+    # This method transmits a process job request to the underlying Unix domain
+    # socket server, which then adds the job to the processing queue. The job
+    # includes the specified command arguments that will be executed by the
+    # probe server.
+    #
+    # @param args [ Array ] the command arguments to be executed by the process
+    # job
+    def enqueue(args)
+      @server.transmit({ type: 'process_job', args: })
+    end
+  end
+end

data/lib/utils/{probe_server.rb → probe/probe_server.rb}

@@ -1,264 +1,4 @@
-require 'unix_socks'
-require 'term/ansicolor'
-
-module Utils
-  # A module that provides server handling functionality for creating and
-  # managing socket servers.
-  #
-  # This module encapsulates the logic for initializing different types of
-  # socket servers based on the specified server type, supporting both TCP and
-  # domain socket configurations. It provides a centralized approach to server
-  # creation and management within the Utils library.
-  module ServerHandling
-    # The create_server method initializes and returns a socket server instance
-    # based on the specified server type.
-    #
-    # This method creates either a TCP socket server or a domain socket server
-    # depending on the server type parameter. It configures the server with the
-    # appropriate parameters including port number for TCP servers or socket
-    # name and runtime directory for domain sockets.
-    #
-    # @param server_type [ Symbol ] the type of socket server to create, either :tcp or another value for domain socket
-    # @param port [ Integer ] the port number to use for TCP socket server creation
-    #
-    # @return [ UnixSocks::TCPSocketServer, UnixSocks::DomainSocketServer ] a
-    #   new socket server instance of the specified type
-    def create_server(server_type, port)
-      case server_type
-      when :tcp
-        UnixSocks::TCPSocketServer.new(port:)
-      else
-        UnixSocks::DomainSocketServer.new(socket_name: 'probe.sock', runtime_dir: Dir.pwd)
-      end
-    end
-  end
-
-  # A process job representation for execution within the probe server system.
-  #
-  # This class encapsulates the information and behavior associated with a
-  # single executable task that can be enqueued and processed by a ProbeServer.
-  # It holds command arguments, manages execution status, and provides
-  # mechanisms for serialization and display of job information.
-  class ProcessJob
-    include Term::ANSIColor
-
-    # Initializes a new ProcessJob instance with the specified arguments and
-    # optional probe server.
-    #
-    # This method creates a process job object that can be enqueued for
-    # execution by a probe server. It assigns a unique job ID from the probe
-    # server if provided and stores the command arguments as an array.
-    #
-    # @param args [ Array ] the command arguments to be executed by the job
-    # @param probe_server [ Utils::ProbeServer, nil ] the probe server instance
-    # to use for generating job IDs
-    #
-    # @return [ Utils::ProcessJob ] a new ProcessJob instance configured with
-    # the provided arguments and server reference
-    def initialize(args:, probe_server: nil)
-      @id   = probe_server&.next_job_id
-      @args = Array(args)
-    end
-
-    # Returns the unique identifier of the process job.
-    #
-    # @return [ Integer ] the job ID
-    attr_reader :id
-
-    # The args reader method provides access to the arguments stored in the
-    # instance.
-    #
-    # @return [ Array ] the array of arguments
-    attr_reader :args
-
-    # The ok method sets the success status of the process job.
-    #
-    # @param value [ TrueClass, FalseClass, nil ] the success status to set
-    attr_writer :ok
-
-    # Returns the type identifier for the process job.
-    #
-    # This method provides a constant string value that identifies the object
-    # as a process job within the probe server system, facilitating type-based
-    # dispatch and handling.
-    #
-    # @return [ String ] the string 'process_job' indicating the object's type
-    def type
-      'process_job'
-    end
-
-    # The ok method returns a character representation of the job's success
-    # status.
-    #
-    # This method provides a visual indicator of whether a process job has
-    # succeeded, failed, or is still in progress. It returns 'y' for successful
-    # jobs, 'n' for failed jobs, and '…' for jobs that are currently running or
-    # pending.
-    #
-    # @return [ String ] 'y' if the job succeeded, 'n' if it failed, or '…' if
-    # the status is unknown
-    def ok
-      case @ok
-      when false then 'n'
-      when true  then 'y'
-      else            '…'
-      end
-    end
-
-    # The ok_colorize method applies color formatting to a string based on the
-    # success status.
-    #
-    # This method returns the input string wrapped with color codes to indicate
-    # whether the associated process job succeeded, failed, or is in progress.
-    # Successful jobs are highlighted in green, failed jobs in red, and pending
-    # jobs are returned without any color formatting.
-    #
-    # @param string [ String ] the string to be colorized
-    #
-    # @return [ String ] the colorized string or the original string if status is unknown
-    def ok_colorize(string)
-      case @ok
-      when false then white { on_red { string } }
-      when true  then black { on_green { string } }
-      else            string
-      end
-    end
-
-    # The inspect method generates a colorized string representation of the
-    # process job.
-    #
-    # This method creates a formatted string that includes the job's unique
-    # identifier and its command arguments, with the status indicator
-    # color-coded based on whether the job succeeded, failed, or is pending.
-    #
-    # @return [ String ] a formatted string representation of the process job
-    #         including its ID, arguments, and color-coded status indicator
-    def inspect
-      ok_colorize("#{id} #{args.map { |a| a.include?(' ') ? a.inspect : a } * ' '}")
-    end
-
-    alias to_s inspect
-
-    # The as_json method converts the process job object into a
-    # JSON-serializable hash.
-    #
-    # This method creates and returns a hash representation of the process job,
-    # containing its type, unique identifier, and command arguments.
-    #
-    # @return [ Hash ] a hash containing the type, id, and args of the process job
-    def as_json(*)
-      { type:, id:, args:, }
-    end
-
-    # The to_json method converts the object to a JSON string representation.
-    #
-    # This method delegates to the as_json method to generate a hash representation
-    # of the object, then converts that hash to a JSON string using the
-    # standard JSON library's to_json method.
-    #
-    # @return [ String ] a JSON string representation of the object
-    def to_json(*)
-      as_json.to_json(*)
-    end
-  end
-
-  # A client for interacting with the probe server through Unix domain sockets.
-  #
-  # This class provides an interface for enqueueing process jobs and managing
-  # environment variables on a remote probe server. It uses Unix domain sockets
-  # to communicate with the server, enabling distributed task execution and
-  # configuration management.
-  class ProbeClient
-    include ServerHandling
-
-    # A proxy class for managing environment variables through a probe server communication channel.
-    #
-    # This class provides a wrapper around the ENV object that allows setting and retrieving
-    # environment variables while logging these operations through the probe server.
-    # It intercepts assignments and lookups to provide visibility into environment modifications
-    # during probe server operations.
-    class EnvProxy
-      # The initialize method sets up a new instance with the provided server
-      # object.
-      #
-      # @param server [ UnixSocks::Server ] the server object to be assigned
-      # to the instance variable
-      def initialize(server)
-        @server = server
-      end
-
-      # The []= method sets an environment variable value through the probe server.
-      #
-      # This method transmits a request to the probe server to set the specified
-      # environment variable key to the given value, then returns the updated
-      # environment value from the server's response.
-      #
-      # @param key [ String ] the environment variable key to set
-      # @param value [ String ] the value to assign to the environment variable
-      #
-      # @return [ String ] the updated environment variable value returned by the server
-      def []=(key, value)
-        response = @server.transmit_with_response(type: 'set_env', key:, value:)
-        response.env
-      end
-
-      # The [] method retrieves the value of an environment variable from the probe server.
-      #
-      # This method sends a request to the probe server to fetch the current value of the specified
-      # environment variable key and returns the corresponding value.
-      #
-      # @param key [ String ] the environment variable key to retrieve
-      #
-      # @return [ String ] the value of the specified environment variable
-      def [](key)
-        response = @server.transmit_with_response(type: 'get_env', key:)
-        response.env
-      end
-
-      attr_reader :env
-    end
-
-    # The initialize method sets up a new probe server instance.
-    #
-    # This method creates and configures a Unix domain socket server for
-    # handling probe jobs and communication. It initializes the server with a
-    # specific socket name and runtime directory, preparing it to listen for
-    # incoming connections and process jobs.
-    #
-    # @return [ Utils::ProbeServer ] a new probe server instance configured with
-    #         the specified socket name and runtime directory
-    def initialize(server_type: :unix, port: 6666)
-      @server = create_server(server_type, port)
-    end
-
-    # The env method provides access to environment variable management through
-    # a proxy object.
-    #
-    # This method returns an EnvProxy instance that allows for setting and
-    # retrieving environment variables via the probe server communication
-    # channel.
-    #
-    # @return [ Utils::ProbeServer::EnvProxy ] a proxy object for environment
-    # variable operations
-    def env
-      EnvProxy.new(@server)
-    end
-
-    # The enqueue method submits a new process job to the probe server for
-    # execution.
-    #
-    # This method transmits a process job request to the underlying Unix domain
-    # socket server, which then adds the job to the processing queue. The job
-    # includes the specified command arguments that will be executed by the
-    # probe server.
-    #
-    # @param args [ Array ] the command arguments to be executed by the process
-    # job
-    def enqueue(args)
-      @server.transmit({ type: 'process_job', args: })
-    end
-  end
-
+module Utils::Probe
   # A probe server for managing and executing process jobs through Unix domain
   # sockets.
   #
@@ -267,7 +7,7 @@ module Utils
   # maintains a queue of jobs, tracks their execution status, and provides an
   # interactive interface for managing the server.
   class ProbeServer
-    include ServerHandling
+    include Utils::Probe::ServerHandling
     include Term::ANSIColor
 
     # The initialize method sets up a new probe server instance.

data/lib/utils/probe/process_job.rb

@@ -0,0 +1,130 @@
+module Utils::Probe
+  # A process job representation for execution within the probe server system.
+  #
+  # This class encapsulates the information and behavior associated with a
+  # single executable task that can be enqueued and processed by a ProbeServer.
+  # It holds command arguments, manages execution status, and provides
+  # mechanisms for serialization and display of job information.
+  class ProcessJob
+    include Term::ANSIColor
+
+    # Initializes a new ProcessJob instance with the specified arguments and
+    # optional probe server.
+    #
+    # This method creates a process job object that can be enqueued for
+    # execution by a probe server. It assigns a unique job ID from the probe
+    # server if provided and stores the command arguments as an array.
+    #
+    # @param args [ Array ] the command arguments to be executed by the job
+    # @param probe_server [ Utils::ProbeServer, nil ] the probe server instance
+    # to use for generating job IDs
+    #
+    # @return [ Utils::ProcessJob ] a new ProcessJob instance configured with
+    # the provided arguments and server reference
+    def initialize(args:, probe_server: nil)
+      @id   = probe_server&.next_job_id
+      @args = Array(args)
+    end
+
+    # Returns the unique identifier of the process job.
+    #
+    # @return [ Integer ] the job ID
+    attr_reader :id
+
+    # The args reader method provides access to the arguments stored in the
+    # instance.
+    #
+    # @return [ Array ] the array of arguments
+    attr_reader :args
+
+    # The ok method sets the success status of the process job.
+    #
+    # @param value [ TrueClass, FalseClass, nil ] the success status to set
+    attr_writer :ok
+
+    # Returns the type identifier for the process job.
+    #
+    # This method provides a constant string value that identifies the object
+    # as a process job within the probe server system, facilitating type-based
+    # dispatch and handling.
+    #
+    # @return [ String ] the string 'process_job' indicating the object's type
+    def type
+      'process_job'
+    end
+
+    # The ok method returns a character representation of the job's success
+    # status.
+    #
+    # This method provides a visual indicator of whether a process job has
+    # succeeded, failed, or is still in progress. It returns 'y' for successful
+    # jobs, 'n' for failed jobs, and '…' for jobs that are currently running or
+    # pending.
+    #
+    # @return [ String ] 'y' if the job succeeded, 'n' if it failed, or '…' if
+    # the status is unknown
+    def ok
+      case @ok
+      when false then 'n'
+      when true  then 'y'
+      else            '…'
+      end
+    end
+
+    # The ok_colorize method applies color formatting to a string based on the
+    # success status.
+    #
+    # This method returns the input string wrapped with color codes to indicate
+    # whether the associated process job succeeded, failed, or is in progress.
+    # Successful jobs are highlighted in green, failed jobs in red, and pending
+    # jobs are returned without any color formatting.
+    #
+    # @param string [ String ] the string to be colorized
+    #
+    # @return [ String ] the colorized string or the original string if status is unknown
+    def ok_colorize(string)
+      case @ok
+      when false then white { on_red { string } }
+      when true  then black { on_green { string } }
+      else            string
+      end
+    end
+
+    # The inspect method generates a colorized string representation of the
+    # process job.
+    #
+    # This method creates a formatted string that includes the job's unique
+    # identifier and its command arguments, with the status indicator
+    # color-coded based on whether the job succeeded, failed, or is pending.
+    #
+    # @return [ String ] a formatted string representation of the process job
+    #         including its ID, arguments, and color-coded status indicator
+    def inspect
+      ok_colorize("#{id} #{args.map { |a| a.include?(' ') ? a.inspect : a } * ' '}")
+    end
+
+    alias to_s inspect
+
+    # The as_json method converts the process job object into a
+    # JSON-serializable hash.
+    #
+    # This method creates and returns a hash representation of the process job,
+    # containing its type, unique identifier, and command arguments.
+    #
+    # @return [ Hash ] a hash containing the type, id, and args of the process job
+    def as_json(*)
+      { type:, id:, args:, }
+    end
+
+    # The to_json method converts the object to a JSON string representation.
+    #
+    # This method delegates to the as_json method to generate a hash representation
+    # of the object, then converts that hash to a JSON string using the
+    # standard JSON library's to_json method.
+    #
+    # @return [ String ] a JSON string representation of the object
+    def to_json(*)
+      as_json.to_json(*)
+    end
+  end
+end

data/lib/utils/probe/server_handling.rb

@@ -0,0 +1,32 @@
+module Utils::Probe
+  # A module that provides server handling functionality for creating and
+  # managing socket servers.
+  #
+  # This module encapsulates the logic for initializing different types of
+  # socket servers based on the specified server type, supporting both TCP and
+  # domain socket configurations. It provides a centralized approach to server
+  # creation and management within the Utils library.
+  module ServerHandling
+    # The create_server method initializes and returns a socket server instance
+    # based on the specified server type.
+    #
+    # This method creates either a TCP socket server or a domain socket server
+    # depending on the server type parameter. It configures the server with the
+    # appropriate parameters including port number for TCP servers or socket
+    # name and runtime directory for domain sockets.
+    #
+    # @param server_type [ Symbol ] the type of socket server to create, either :tcp or another value for domain socket
+    # @param port [ Integer ] the port number to use for TCP socket server creation
+    #
+    # @return [ UnixSocks::TCPSocketServer, UnixSocks::DomainSocketServer ] a
+    #   new socket server instance of the specified type
+    def create_server(server_type, port)
+      case server_type
+      when :tcp
+        UnixSocks::TCPSocketServer.new(port:)
+      else
+        UnixSocks::DomainSocketServer.new(socket_name: 'probe.sock', runtime_dir: Dir.pwd)
+      end
+    end
+  end
+end

data/lib/utils/probe.rb

@@ -0,0 +1,23 @@
+# A module that provides probe server functionality for managing and executing
+# process jobs through Unix domain sockets.
+#
+# This module encapsulates the core components for creating and interacting
+# with probe servers that can enqueue and run process jobs in a distributed
+# manner.
+#
+# The module includes classes for handling server communication, managing
+# process jobs, and providing client interfaces for interacting with probe
+# servers.
+#
+# It supports both TCP and Unix domain socket configurations for server
+# communication and provides mechanisms for environment variable management and
+# job execution tracking.
+module Utils::Probe
+end
+
+require 'unix_socks'
+require 'term/ansicolor'
+require 'utils/probe/server_handling'
+require 'utils/probe/process_job'
+require 'utils/probe/probe_server'
+require 'utils/probe/probe_client'

data/lib/utils/version.rb

@@ -1,6 +1,6 @@
 module Utils
   # Utils version
-  VERSION         = '0.81.0'
+  VERSION         = '0.83.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/utils.rb

@@ -14,7 +14,7 @@ module Utils
   require 'utils/editor'
   require 'utils/finder'
   require 'utils/grepper'
-  require 'utils/probe_server'
+  require 'utils/probe'
   require 'utils/ssh_tunnel_specification'
   require 'utils/line_blamer'
   require 'utils/config_dir'

data/utils.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: utils 0.81.0 ruby lib
+# stub: utils 0.83.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "utils".freeze
-  s.version = "0.81.0".freeze
+  s.version = "0.83.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -11,9 +11,9 @@ Gem::Specification.new do |s|
   s.date = "1980-01-02"
   s.description = "This ruby gem provides some useful command line utilities".freeze
   s.email = "flori@ping.de".freeze
-  s.executables = ["ascii7".freeze, "blameline".freeze, "changes".freeze, "classify".freeze, "code_comment".freeze, "code_indexer".freeze, "commit_message".freeze, "discover".freeze, "edit".freeze, "edit_wait".freeze, "enum".freeze, "git-empty".freeze, "git-versions".freeze, "json_check".freeze, "long_lines".freeze, "myex".freeze, "on_change".freeze, "path".freeze, "print_method".freeze, "probe".freeze, "rainbow".freeze, "rd2md".freeze, "search".freeze, "sedit".freeze, "serve".freeze, "ssh-tunnel".freeze, "strip_spaces".freeze, "sync_dir".freeze, "untest".freeze, "utils-utilsrc".freeze, "vcf2alias".freeze, "yaml_check".freeze]
-  s.extra_rdoc_files = ["README.md".freeze, "lib/utils.rb".freeze, "lib/utils/config_dir.rb".freeze, "lib/utils/config_file.rb".freeze, "lib/utils/editor.rb".freeze, "lib/utils/finder.rb".freeze, "lib/utils/grepper.rb".freeze, "lib/utils/irb.rb".freeze, "lib/utils/line_blamer.rb".freeze, "lib/utils/line_formatter.rb".freeze, "lib/utils/md5.rb".freeze, "lib/utils/patterns.rb".freeze, "lib/utils/probe_server.rb".freeze, "lib/utils/ssh_tunnel_specification.rb".freeze, "lib/utils/version.rb".freeze, "lib/utils/xt/source_location_extension.rb".freeze]
-  s.files = ["Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "bin/ascii7".freeze, "bin/blameline".freeze, "bin/changes".freeze, "bin/classify".freeze, "bin/code_comment".freeze, "bin/code_indexer".freeze, "bin/commit_message".freeze, "bin/discover".freeze, "bin/edit".freeze, "bin/edit_wait".freeze, "bin/enum".freeze, "bin/git-empty".freeze, "bin/git-versions".freeze, "bin/json_check".freeze, "bin/long_lines".freeze, "bin/myex".freeze, "bin/on_change".freeze, "bin/path".freeze, "bin/print_method".freeze, "bin/probe".freeze, "bin/rainbow".freeze, "bin/rd2md".freeze, "bin/search".freeze, "bin/sedit".freeze, "bin/serve".freeze, "bin/ssh-tunnel".freeze, "bin/strip_spaces".freeze, "bin/sync_dir".freeze, "bin/untest".freeze, "bin/utils-utilsrc".freeze, "bin/vcf2alias".freeze, "bin/yaml_check".freeze, "lib/utils.rb".freeze, "lib/utils/config_dir.rb".freeze, "lib/utils/config_file.rb".freeze, "lib/utils/editor.rb".freeze, "lib/utils/finder.rb".freeze, "lib/utils/grepper.rb".freeze, "lib/utils/irb.rb".freeze, "lib/utils/line_blamer.rb".freeze, "lib/utils/line_formatter.rb".freeze, "lib/utils/md5.rb".freeze, "lib/utils/patterns.rb".freeze, "lib/utils/probe_server.rb".freeze, "lib/utils/ssh_tunnel_specification.rb".freeze, "lib/utils/version.rb".freeze, "lib/utils/xt/source_location_extension.rb".freeze, "tests/test_helper.rb".freeze, "tests/utils_test.rb".freeze, "utils.gemspec".freeze]
+  s.executables = ["ascii7".freeze, "blameline".freeze, "changes".freeze, "classify".freeze, "code_comment".freeze, "code_indexer".freeze, "commit_message".freeze, "discover".freeze, "edit".freeze, "edit_wait".freeze, "enum".freeze, "git-empty".freeze, "git-versions".freeze, "irb_client".freeze, "json_check".freeze, "long_lines".freeze, "myex".freeze, "on_change".freeze, "path".freeze, "print_method".freeze, "probe".freeze, "rainbow".freeze, "rd2md".freeze, "search".freeze, "sedit".freeze, "serve".freeze, "ssh-tunnel".freeze, "strip_spaces".freeze, "sync_dir".freeze, "untest".freeze, "utils-utilsrc".freeze, "vcf2alias".freeze, "yaml_check".freeze]
+  s.extra_rdoc_files = ["README.md".freeze, "lib/utils.rb".freeze, "lib/utils/config_dir.rb".freeze, "lib/utils/config_file.rb".freeze, "lib/utils/editor.rb".freeze, "lib/utils/finder.rb".freeze, "lib/utils/grepper.rb".freeze, "lib/utils/irb.rb".freeze, "lib/utils/irb/irb_server.rb".freeze, "lib/utils/line_blamer.rb".freeze, "lib/utils/line_formatter.rb".freeze, "lib/utils/md5.rb".freeze, "lib/utils/patterns.rb".freeze, "lib/utils/probe.rb".freeze, "lib/utils/probe/probe_client.rb".freeze, "lib/utils/probe/probe_server.rb".freeze, "lib/utils/probe/process_job.rb".freeze, "lib/utils/probe/server_handling.rb".freeze, "lib/utils/ssh_tunnel_specification.rb".freeze, "lib/utils/version.rb".freeze, "lib/utils/xt/source_location_extension.rb".freeze]
+  s.files = ["Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "bin/ascii7".freeze, "bin/blameline".freeze, "bin/changes".freeze, "bin/classify".freeze, "bin/code_comment".freeze, "bin/code_indexer".freeze, "bin/commit_message".freeze, "bin/discover".freeze, "bin/edit".freeze, "bin/edit_wait".freeze, "bin/enum".freeze, "bin/git-empty".freeze, "bin/git-versions".freeze, "bin/irb_client".freeze, "bin/json_check".freeze, "bin/long_lines".freeze, "bin/myex".freeze, "bin/on_change".freeze, "bin/path".freeze, "bin/print_method".freeze, "bin/probe".freeze, "bin/rainbow".freeze, "bin/rd2md".freeze, "bin/search".freeze, "bin/sedit".freeze, "bin/serve".freeze, "bin/ssh-tunnel".freeze, "bin/strip_spaces".freeze, "bin/sync_dir".freeze, "bin/untest".freeze, "bin/utils-utilsrc".freeze, "bin/vcf2alias".freeze, "bin/yaml_check".freeze, "lib/utils.rb".freeze, "lib/utils/config_dir.rb".freeze, "lib/utils/config_file.rb".freeze, "lib/utils/editor.rb".freeze, "lib/utils/finder.rb".freeze, "lib/utils/grepper.rb".freeze, "lib/utils/irb.rb".freeze, "lib/utils/irb/irb_server.rb".freeze, "lib/utils/line_blamer.rb".freeze, "lib/utils/line_formatter.rb".freeze, "lib/utils/md5.rb".freeze, "lib/utils/patterns.rb".freeze, "lib/utils/probe.rb".freeze, "lib/utils/probe/probe_client.rb".freeze, "lib/utils/probe/probe_server.rb".freeze, "lib/utils/probe/process_job.rb".freeze, "lib/utils/probe/server_handling.rb".freeze, "lib/utils/ssh_tunnel_specification.rb".freeze, "lib/utils/version.rb".freeze, "lib/utils/xt/source_location_extension.rb".freeze, "tests/test_helper.rb".freeze, "tests/utils_test.rb".freeze, "utils.gemspec".freeze]
   s.homepage = "http://github.com/flori/utils".freeze
   s.licenses = ["GPL-2.0".freeze]
   s.rdoc_options = ["--title".freeze, "Utils - Some useful command line utilities".freeze, "--main".freeze, "README.md".freeze]
@@ -23,7 +23,7 @@ Gem::Specification.new do |s|
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, [">= 2.16.2".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, [">= 2.16.3".freeze])
   s.add_development_dependency(%q<test-unit>.freeze, [">= 0".freeze])
   s.add_runtime_dependency(%q<unix_socks>.freeze, ["~> 0.3".freeze])
   s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.51".freeze])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utils
 version: !ruby/object:Gem::Version
-  version: 0.81.0
+  version: 0.83.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.16.2
+        version: 2.16.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.16.2
+        version: 2.16.3
 - !ruby/object:Gem::Dependency
   name: test-unit
   requirement: !ruby/object:Gem::Requirement
@@ -277,6 +277,7 @@ executables:
 - enum
 - git-empty
 - git-versions
+- irb_client
 - json_check
 - long_lines
 - myex
@@ -306,11 +307,16 @@ extra_rdoc_files:
 - lib/utils/finder.rb
 - lib/utils/grepper.rb
 - lib/utils/irb.rb
+- lib/utils/irb/irb_server.rb
 - lib/utils/line_blamer.rb
 - lib/utils/line_formatter.rb
 - lib/utils/md5.rb
 - lib/utils/patterns.rb
-- lib/utils/probe_server.rb
+- lib/utils/probe.rb
+- lib/utils/probe/probe_client.rb
+- lib/utils/probe/probe_server.rb
+- lib/utils/probe/process_job.rb
+- lib/utils/probe/server_handling.rb
 - lib/utils/ssh_tunnel_specification.rb
 - lib/utils/version.rb
 - lib/utils/xt/source_location_extension.rb
@@ -332,6 +338,7 @@ files:
 - bin/enum
 - bin/git-empty
 - bin/git-versions
+- bin/irb_client
 - bin/json_check
 - bin/long_lines
 - bin/myex
@@ -358,11 +365,16 @@ files:
 - lib/utils/finder.rb
 - lib/utils/grepper.rb
 - lib/utils/irb.rb
+- lib/utils/irb/irb_server.rb
 - lib/utils/line_blamer.rb
 - lib/utils/line_formatter.rb
 - lib/utils/md5.rb
 - lib/utils/patterns.rb
-- lib/utils/probe_server.rb
+- lib/utils/probe.rb
+- lib/utils/probe/probe_client.rb
+- lib/utils/probe/probe_server.rb
+- lib/utils/probe/process_job.rb
+- lib/utils/probe/server_handling.rb
 - lib/utils/ssh_tunnel_specification.rb
 - lib/utils/version.rb
 - lib/utils/xt/source_location_extension.rb