ruby_llm-docker 0.2.5 → 0.3.0

data/lib/ruby_llm/docker/remove_network.rb

@@ -2,110 +2,72 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for removing Docker networks.
+    # MCP tool for removing Docker networks.
     #
-    # This tool provides the ability to permanently delete Docker networks from
-    # the system. It safely removes custom networks while protecting built-in
-    # system networks from accidental deletion.
+    # This tool provides the ability to delete Docker networks when they
+    # are no longer needed. Network removal helps maintain clean network
+    # configurations and prevents resource leaks.
     #
     # == Features
     #
-    # - Remove custom Docker networks by ID or name
-    # - Protection against removing built-in networks
+    # - Remove networks by ID or name
+    # - Validation of network existence
     # - Comprehensive error handling
-    # - Dependency checking (prevents removal if containers are connected)
+    # - Prevention of removing networks in use
     # - Safe cleanup of network resources
-    #
-    # == ⚠️ Service Disruption Warning ⚠️
-    #
-    # **NETWORK REMOVAL CAN DISRUPT SERVICES**
-    #
-    # Removing networks can cause immediate service disruption:
-    # - Connected containers lose network connectivity
-    # - Inter-container communication is broken
-    # - Services may become unreachable
-    # - Application functionality can be severely impacted
-    # - Network-dependent processes may fail
-    #
-    # == Protected Networks
-    #
-    # Docker protects certain built-in networks from removal:
-    # - **bridge**: Default bridge network
-    # - **host**: Host networking
-    # - **none**: No networking
-    # - **System networks**: Docker-managed networks
+    # - Network dependency checking
     #
     # == Security Considerations
     #
-    # Network removal affects security boundaries:
-    # - Removes network isolation between containers
-    # - May expose containers to unintended networks
-    # - Could impact security segmentation strategies
-    # - Affects network-based access controls
+    # Network removal involves important considerations:
+    # - **Service Disruption**: Removing active networks disconnects containers
+    # - **Data Isolation**: Network removal can affect container communication
+    # - **Resource Cleanup**: Improper removal can leave network artifacts
+    # - **Container Dependencies**: Containers may fail without expected networks
+    # - **Network Policies**: Removal affects security and access policies
     #
-    # Security implications:
-    # - Ensure no critical containers depend on the network
-    # - Verify alternative connectivity exists if needed
-    # - Consider impact on security boundaries
-    # - Monitor for unauthorized network modifications
+    # **Security Recommendations**:
+    # - Verify no containers are connected before removal
+    # - Check for dependent services and applications
+    # - Document network removal in change logs
+    # - Implement network lifecycle management
+    # - Monitor for orphaned network resources
+    # - Use network removal as part of cleanup procedures
     #
-    # Best practices:
-    # - Stop containers before removing their networks
-    # - Verify network dependencies before removal
-    # - Have rollback plans for critical networks
-    # - Document network removal procedures
-    # - Monitor network connectivity after removal
+    # == Parameters
+    #
+    # - **id**: Network ID or name (required)
     #
     # == Example Usage
     #
-    #   # Remove custom network
-    #   RemoveNetwork.call(
+    #   # Remove network by name
+    #   response = RemoveNetwork.call(
     #     server_context: context,
     #     id: "app-network"
     #   )
     #
-    #   # Remove by network ID
-    #   RemoveNetwork.call(
+    #   # Remove network by ID
+    #   response = RemoveNetwork.call(
     #     server_context: context,
     #     id: "abc123def456"
     #   )
     #
-    # @see CreateNetwork
-    # @see ListNetworks
-    # @see Docker::Network#delete
+    #   # Clean up test networks
+    #   response = RemoveNetwork.call(
+    #     server_context: context,
+    #     id: "test-isolated-network"
+    #   )
+    #
+    # @see ::Docker::Network#delete
     # @since 0.1.0
-    class RemoveNetwork < RubyLLM::Tool
+    REMOVE_NETWORK_DEFINITION = ToolForge.define(:remove_network) do
       description 'Remove a Docker network'
 
-      param :id, type: :string, desc: 'Network ID or name'
+      param :id,
+            type: :string,
+            description: 'Network ID or name'
 
-      # Remove a Docker network from the system.
-      #
-      # This method permanently deletes the specified network. The network
-      # must not have any containers connected to it, and built-in system
-      # networks cannot be removed.
-      #
-      # @param id [String] network ID or name to remove
-      # @param server_context [Object] RubyLLM context (unused but required)
-      #
-      # @return [RubyLLM::Tool::Response] removal operation results
-      #
-      # @raise [Docker::Error::NotFoundError] if network doesn't exist
-      # @raise [StandardError] for removal failures or dependency conflicts
-      #
-      # @example Remove custom network
-      #   response = RemoveNetwork.call(
-      #     server_context: context,
-      #     id: "frontend-network"
-      #   )
-      #
-      # @example Remove by ID
-      #   response = tool.execute(
-      #     id: "1a2b3c4d5e6f"
-      #   )
-      #
-      # @see Docker::Network#delete
-      def execute(id:)
+      execute do |id:|
         network = ::Docker::Network.get(id)
         network.delete
 
@@ -116,5 +78,7 @@ module RubyLLM
         "Error removing network: #{e.message}"
       end
     end
+
+    RemoveNetwork = REMOVE_NETWORK_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/remove_volume.rb

@@ -2,117 +2,82 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for removing Docker volumes.
+    # MCP tool for removing Docker volumes.
     #
-    # This tool provides the ability to permanently delete Docker volumes from
-    # the system. This is a destructive operation that will permanently delete
-    # all data stored in the volume.
+    # This tool provides the ability to delete Docker volumes when they
+    # are no longer needed. Volume removal is critical for preventing
+    # storage leaks and maintaining clean Docker environments.
     #
     # == Features
     #
-    # - Remove Docker volumes by name
-    # - Force removal option for volumes in use
+    # - Remove volumes by name
+    # - Force removal of volumes in use
+    # - Validation of volume existence
     # - Comprehensive error handling
-    # - Dependency checking (prevents removal if containers are using the volume)
-    # - Safe cleanup of storage resources
-    #
-    # == ⚠️ CRITICAL DATA LOSS WARNING ⚠️
-    #
-    # **DESTRUCTIVE OPERATION - PERMANENT DATA LOSS**
-    #
-    # This operation permanently and irreversibly deletes data:
-    # - **ALL DATA** in the volume is deleted forever
-    # - No recovery possible after deletion
-    # - Applications may lose critical data
-    # - Databases and persistent state are destroyed
-    # - Configuration files and user data are lost
-    # - Operation cannot be undone
-    #
-    # == Volume Dependencies
-    #
-    # Volumes may have active dependencies:
-    # - **Running Containers**: Containers currently using the volume
-    # - **Stopped Containers**: Containers that could be restarted
-    # - **Application Data**: Critical application state and databases
-    # - **User Data**: User-generated content and files
+    # - Safe volume cleanup procedures
+    # - Prevention of accidental data loss
     #
     # == Security Considerations
     #
-    # Volume removal has security implications:
-    # - Sensitive data is not securely wiped
-    # - Data may be recoverable from disk sectors
-    # - Shared volumes may affect multiple applications
-    # - Removal logs may reveal data existence
+    # Volume removal involves critical data considerations:
+    # - **Data Loss**: Removed volumes and their data are permanently deleted
+    # - **Service Disruption**: Removing volumes can break running containers
+    # - **Data Recovery**: Volume data cannot be recovered after removal
+    # - **Container Dependencies**: Applications may fail without expected volumes
+    # - **Storage Cleanup**: Improper removal can leave orphaned data
+    # - **Backup Requirements**: Critical data should be backed up before removal
     #
-    # Critical security measures:
-    # - **Backup critical data** before removal
-    # - Verify no containers depend on the volume
-    # - Consider secure data wiping for sensitive volumes
-    # - Audit volume removal operations
-    # - Monitor for unauthorized volume deletions
+    # **Security Recommendations**:
+    # - Always backup critical data before volume removal
+    # - Verify no containers are using the volume
+    # - Use force option only when absolutely necessary
+    # - Document volume removal in change management
+    # - Implement volume lifecycle and retention policies
+    # - Monitor storage usage after volume removal
+    # - Consider data migration instead of removal
     #
-    # == Force Removal Risks
+    # == Parameters
     #
-    # Force removal bypasses safety checks:
-    # - Removes volumes even if containers are using them
-    # - Can cause immediate application failures
-    # - May corrupt running applications
-    # - Data loss occurs immediately
+    # - **name**: Volume name (required)
+    # - **force**: Force removal of the volume (optional, default: false)
     #
     # == Example Usage
     #
-    #   # Safe removal of unused volume
-    #   RemoveVolume.call(
+    #   # Remove unused volume
+    #   response = RemoveVolume.call(
     #     server_context: context,
-    #     name: "temp-data"
+    #     name: "old-app-data"
     #   )
     #
-    #   # Force removal of volume in use (DANGEROUS)
-    #   RemoveVolume.call(
+    #   # Force remove volume in use
+    #   response = RemoveVolume.call(
     #     server_context: context,
     #     name: "stuck-volume",
     #     force: true
     #   )
     #
-    # @see CreateVolume
-    # @see ListVolumes
-    # @see Docker::Volume#remove
+    #   # Clean up test volumes
+    #   response = RemoveVolume.call(
+    #     server_context: context,
+    #     name: "test-data-volume"
+    #   )
+    #
+    # @see ::Docker::Volume#remove
     # @since 0.1.0
-    class RemoveVolume < RubyLLM::Tool
+    REMOVE_VOLUME_DEFINITION = ToolForge.define(:remove_volume) do
       description 'Remove a Docker volume'
 
-      param :name, type: :string, desc: 'Volume name'
-      param :force, type: :boolean, desc: 'Force removal of the volume (default: false)', required: false
+      param :name,
+            type: :string,
+            description: 'Volume name'
 
-      # Remove a Docker volume permanently from the system.
-      #
-      # This method permanently deletes the specified volume and all data
-      # contained within it. By default, it performs safety checks to prevent
-      # removal of volumes with active container dependencies.
-      #
-      # @param name [String] name of the volume to remove
-      # @param server_context [Object] RubyLLM context (unused but required)
-      # @param force [Boolean] whether to force removal despite dependencies (default: false)
-      #
-      # @return [RubyLLM::Tool::Response] removal operation results
-      #
-      # @raise [Docker::Error::NotFoundError] if volume doesn't exist
-      # @raise [StandardError] for removal failures or dependency conflicts
-      #
-      # @example Remove unused volume
-      #   response = RemoveVolume.call(
-      #     server_context: context,
-      #     name: "old-cache-data"
-      #   )
-      #
-      # @example Force remove problematic volume
-      #   response = tool.execute(
-      #     name: "corrupted-volume",
-      #     force: true
-      #   )
-      #
-      # @see Docker::Volume#remove
-      def execute(name:, force: false)
+      param :force,
+            type: :boolean,
+            description: 'Force removal of the volume (default: false)',
+            required: false,
+            default: false
+
+      execute do |name:, force: false|
         volume = ::Docker::Volume.get(name)
         volume.remove(force: force)
 
@@ -123,5 +88,7 @@ module RubyLLM
         "Error removing volume: #{e.message}"
       end
     end
+
+    RemoveVolume = REMOVE_VOLUME_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/run_container.rb

@@ -2,87 +2,105 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for running Docker containers (create and start in one operation).
+    # MCP tool for running Docker containers.
     #
-    # This tool provides a convenient way to create and immediately start Docker
-    # containers from images. It combines the functionality of container creation
-    # and startup into a single operation, which is the most common use case for
-    # Docker containers.
+    # This tool creates and immediately starts a Docker container from a
+    # specified image in a single operation. It combines the functionality
+    # of create_container and start_container for convenience when immediate
+    # execution is desired.
     #
     # == Features
     #
-    # - Create and start containers in one operation
-    # - Full support for container configuration options
-    # - Port mapping and network configuration
-    # - Volume mounting capabilities
-    # - Environment variable configuration
-    # - Custom command execution
-    # - Comprehensive error handling
+    # - Creates and starts containers in one operation
+    # - Supports all container configuration options
+    # - Configures command execution and environment variables
+    # - Sets up port exposure and network configuration
+    # - Applies advanced host configurations and volume mounts
+    # - Handles container naming and labeling
     #
     # == Security Considerations
     #
-    # - Containers inherit Docker daemon privileges
-    # - Port mappings expose services to host network
-    # - Volume mounts provide filesystem access
-    # - Environment variables may contain sensitive data
-    # - Custom commands can execute arbitrary code
+    # Running containers involves significant security considerations:
+    # - **Immediate Execution**: Starts processes immediately upon creation
+    # - **Resource Consumption**: Consumes CPU, memory, and storage resources
+    # - **Network Exposure**: Creates active network endpoints
+    # - **File System Access**: Potentially accesses host directories
+    # - **Process Isolation**: Runs processes with configured privileges
     #
-    # Use appropriate security measures:
-    # - Run containers with minimal required privileges
-    # - Limit port exposure to necessary services only
-    # - Use read-only volumes where possible
-    # - Avoid mounting sensitive host directories
-    # - Validate environment variables for secrets
+    # Implement strict access controls and resource monitoring.
+    #
+    # == Parameters
+    #
+    # - **image**: Docker image to use (required)
+    # - **name**: Custom container name (optional)
+    # - **cmd**: Command to execute as space-separated string (optional)
+    # - **env**: Environment variables as comma-separated KEY=VALUE pairs (optional)
+    # - **exposed_ports**: Port exposure configuration as JSON object (optional)
+    # - **host_config**: Advanced host configuration as JSON object (optional)
     #
     # == Example Usage
     #
-    #   # Simple container run
-    #   RunContainer.call(
+    #   # Simple container execution
+    #   response = RunContainer.call(
     #     server_context: context,
-    #     image: "nginx:latest",
-    #     name: "web-server"
+    #     image: "alpine:latest",
+    #     cmd: "echo 'Hello World'"
     #   )
     #
-    #   # Advanced configuration with ports and volumes
-    #   RunContainer.call(
+    #   # Web server with port binding
+    #   response = RunContainer.call(
     #     server_context: context,
-    #     image: "postgres:13",
-    #     name: "database",
-    #     env: ["POSTGRES_PASSWORD=secret"],
+    #     image: "nginx:latest",
+    #     name: "web-server",
+    #     exposed_ports: {"80/tcp" => {}},
     #     host_config: {
-    #       "PortBindings" => {"5432/tcp" => [{"HostPort" => "5432"}]},
-    #       "Binds" => ["/host/data:/var/lib/postgresql/data"]
+    #       "PortBindings" => {"80/tcp" => [{"HostPort" => "8080"}]}
     #     }
     #   )
     #
-    # @see CreateContainer
-    # @see StartContainer
-    # @see Docker::Container.create
+    # @see ::Docker::Container.create
     # @since 0.1.0
-    class RunContainer < RubyLLM::Tool
+    RUN_CONTAINER_DEFINITION = ToolForge.define(:run_container) do
       description 'Run a Docker container (create and start)'
 
-      param :image, desc: 'Image name to use (e.g., "ubuntu:22.04")'
-      param :name, desc: 'Container name (optional)', required: false
-      param :cmd, desc: 'Command to run (optional)', required: false
+      param :image,
+            type: :string,
+            description: 'Image name to use (e.g., "ubuntu:22.04")'
+
+      param :name,
+            type: :string,
+            description: 'Container name (optional)',
+            required: false
+
+      param :cmd,
+            type: :string,
+            description: 'Command to run as space-separated string (optional, e.g., "npm start" or "python app.py")',
+            required: false
+
       param :env,
-            desc: 'Environment variables as comma-separated KEY=VALUE pairs ' \
-                  '(optional, e.g., "VAR1=value1,VAR2=value2")',
+            type: :string,
+            description: 'Environment variables as comma-separated KEY=VALUE pairs (optional)',
+            required: false
+
+      param :exposed_ports,
+            type: :object,
+            description: 'Exposed ports as {"port/protocol": {}} (optional)',
             required: false
-      param :exposed_ports, desc: 'Exposed ports as JSON object (optional)', required: false
-      param :host_config, desc: 'Host configuration including port bindings, volumes, etc.',
-                          required: false
 
-      def execute(image:, name: nil, cmd: nil, env: nil, exposed_ports: nil, host_config: nil)
+      param :host_config,
+            type: :object,
+            description: 'Host configuration including port bindings, volumes, etc. (optional)',
+            required: false
+
+      execute do |image:, name: nil, cmd: nil, env: nil, exposed_ports: nil, host_config: nil|
         config = { 'Image' => image }
         config['name'] = name if name
-        config['Cmd'] = cmd if cmd
 
-        # Parse environment variables string into array if provided
-        if env && !env.empty?
-          env_array = env.split(',').map(&:strip).select { |e| e.include?('=') }
-          config['Env'] = env_array unless env_array.empty?
-        end
+        # Parse cmd string into array if provided
+        config['Cmd'] = Shellwords.split(cmd) if cmd && !cmd.strip.empty?
+
+        # Parse env string into array if provided
+        config['Env'] = env.split(',').map(&:strip) if env && !env.strip.empty?
 
         config['ExposedPorts'] = exposed_ports if exposed_ports
         config['HostConfig'] = host_config if host_config
@@ -100,5 +118,7 @@ module RubyLLM
         "Error running container: #{e.message}"
       end
     end
+
+    RunContainer = RUN_CONTAINER_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/start_container.rb

@@ -2,87 +2,62 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for starting existing Docker containers.
+    # MCP tool for starting Docker containers.
     #
-    # This tool provides the ability to start Docker containers that have been
-    # created but are currently stopped. It's the counterpart to StopContainer
-    # and is commonly used after CreateContainer or when restarting stopped
-    # containers.
+    # This tool starts a previously created Docker container that is currently
+    # in a "created" or "stopped" state. It transitions the container to a
+    # "running" state and begins executing the configured command or entrypoint.
     #
     # == Features
     #
-    # - Start stopped containers by ID or name
-    # - Simple and reliable container lifecycle management
-    # - Comprehensive error handling
-    # - Works with containers in any stopped state
+    # - Starts containers by ID or name
+    # - Supports both short and full container IDs
+    # - Works with custom container names
+    # - Provides clear success/failure feedback
+    # - Handles container state transitions
+    # - Preserves all container configuration
     #
     # == Security Considerations
     #
-    # Starting containers can have security implications:
-    # - Containers resume with their original configuration
-    # - Services become accessible on mapped ports
-    # - Processes resume execution with previous privileges
-    # - Network connections are re-established
+    # Starting containers involves security implications:
+    # - **Process Execution**: Begins running container processes
+    # - **Resource Activation**: Activates CPU, memory, and I/O usage
+    # - **Network Activation**: Brings network interfaces online
+    # - **Service Exposure**: Makes configured services accessible
     #
-    # Ensure containers are properly configured before starting:
-    # - Review port mappings and network exposure
-    # - Verify volume mounts and file permissions
-    # - Check environment variables for sensitive data
-    # - Validate container image integrity
+    # Ensure proper monitoring and access controls are in place.
+    #
+    # == Parameters
+    #
+    # - **id**: Container ID or name (required)
+    #   - Accepts full container IDs
+    #   - Accepts short container IDs (first 12+ characters)
+    #   - Accepts custom container names
     #
     # == Example Usage
     #
-    #   # Start container by name
-    #   StartContainer.call(
+    #   # Start by container name
+    #   response = StartContainer.call(
     #     server_context: context,
     #     id: "web-server"
     #   )
     #
-    #   # Start container by ID
-    #   StartContainer.call(
+    #   # Start by container ID
+    #   response = StartContainer.call(
     #     server_context: context,
     #     id: "a1b2c3d4e5f6"
     #   )
     #
-    # @see CreateContainer
-    # @see StopContainer
-    # @see RunContainer
-    # @see Docker::Container#start
+    # @see ::Docker::Container#start
     # @since 0.1.0
-    class StartContainer < RubyLLM::Tool
+    START_CONTAINER_DEFINITION = ToolForge.define(:start_container) do
       description 'Start a Docker container'
 
-      param :id, desc: 'Container ID or name'
+      param :id,
+            type: :string,
+            description: 'Container ID or name'
 
-      # Start an existing Docker container.
-      #
-      # This method starts a container that is currently in a stopped state.
-      # The container must already exist and be in a startable state. If the
-      # container is already running, Docker will typically ignore the start
-      # command without error.
-      #
-      # @param id [String] container ID (full or short) or container name
-      # @param server_context [Object] RubyLLM context (unused but required)
-      #
-      # @return [RubyLLM::Tool::Response] start operation results
-      #
-      # @raise [Docker::Error::NotFoundError] if container doesn't exist
-      # @raise [StandardError] for other start failures
-      #
-      # @example Start by container name
-      #   response = StartContainer.call(
-      #     server_context: context,
-      #     id: "my-app-container"
-      #   )
-      #
-      # @example Start by container ID
-      #   response = StartContainer.call(
-      #     server_context: context,
-      #     id: "abc123def456"
-      #   )
-      #
-      # @see Docker::Container#start
-      def execute(id:)
+      execute do |id:|
         container = ::Docker::Container.get(id)
         container.start
 
@@ -93,5 +68,7 @@ module RubyLLM
         "Error starting container: #{e.message}"
       end
     end
+
+    StartContainer = START_CONTAINER_DEFINITION.to_ruby_llm_tool
   end
 end