ruby_llm-docker 0.0.1 → 0.3.0

data/lib/ruby_llm/docker/push_image.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for pushing Docker images to registries.
+    #
+    # This tool provides the ability to upload Docker images to Docker
+    # registries such as Docker Hub, private registries, or cloud-based
+    # container registries. It supports various push configurations and
+    # authentication scenarios.
+    #
+    # == Features
+    #
+    # - Push images to any Docker registry
+    # - Support for tagged and untagged pushes
+    # - Registry authentication integration
+    # - Comprehensive error handling and validation
+    # - Multi-registry support
+    # - Progress tracking and status reporting
+    # - Registry namespace validation
+    #
+    # == Security Considerations
+    #
+    # Pushing images involves significant security risks:
+    # - **Credential Exposure**: Registry credentials may be exposed
+    # - **Image Integrity**: Pushed images become publicly accessible
+    # - **Supply Chain Risk**: Malicious images can be distributed
+    # - **Registry Security**: Vulnerable registries can be compromised
+    # - **Network Exposure**: Push operations traverse networks
+    # - **Access Control**: Improper permissions can lead to unauthorized access
+    #
+    # **Security Recommendations**:
+    # - Use secure registry authentication
+    # - Scan images for vulnerabilities before pushing
+    # - Implement image signing and verification
+    # - Use private registries for sensitive images
+    # - Monitor registry access and usage
+    # - Implement proper RBAC for registry operations
+    # - Validate image content before distribution
+    #
+    # == Parameters
+    #
+    # - **name**: Image name or ID to push (required)
+    # - **tag**: Tag to push (optional, pushes all tags if not specified)
+    # - **repo_tag**: Full repo:tag to push (optional, e.g., "registry/repo:tag")
+    #
+    # == Example Usage
+    #
+    #   # Push to Docker Hub
+    #   response = PushImage.call(
+    #     server_context: context,
+    #     name: "username/myapp",
+    #     tag: "v1.0.0"
+    #   )
+    #
+    #   # Push to private registry
+    #   response = PushImage.call(
+    #     server_context: context,
+    #     name: "myapp",
+    #     repo_tag: "registry.company.com/team/myapp:latest"
+    #   )
+    #
+    #   # Push all tags
+    #   response = PushImage.call(
+    #     server_context: context,
+    #     name: "username/myapp"
+    #   )
+    #
+    # @see Docker CLI push command
+    # @since 0.1.0
+    PUSH_IMAGE_DEFINITION = ToolForge.define(:push_image) do
+      description 'Push a Docker image'
+
+      param :name,
+            type: :string,
+            description: 'Image name or ID to push'
+
+      param :tag,
+            type: :string,
+            description: 'Tag to push (optional, pushes all tags if not specified)',
+            required: false
+
+      param :repo_tag,
+            type: :string,
+            description: 'Full repo:tag to push (e.g., "registry/repo:tag") (optional)',
+            required: false
+
+      execute do |name:, tag: nil, repo_tag: nil|
+        # Construct the full image identifier
+        image_identifier = tag ? "#{name}:#{tag}" : name
+
+        # Validate that the image name includes a registry/username
+        unless name.include?('/') || repo_tag&.include?('/')
+          next 'Error: Image name must include registry/username ' \
+               "(e.g., 'username/#{name}'). Local images cannot be " \
+               'pushed without a registry prefix.'
+        end
+
+        # Verify the image exists
+        begin
+          ::Docker::Image.get(image_identifier)
+        rescue ::Docker::Error::NotFoundError
+          next "Image #{image_identifier} not found"
+        end
+
+        # Use the Docker CLI to push the image
+        push_target = repo_tag || image_identifier
+        _, stderr, status = Open3.capture3('docker', 'push', push_target)
+
+        if status.success?
+          "Image #{push_target} pushed successfully"
+        else
+          error_msg = stderr.strip
+          error_msg = 'Failed to push image' if error_msg.empty?
+          "Error pushing image: #{error_msg}"
+        end
+      rescue StandardError => e
+        "Error pushing image: #{e.message}"
+      end
+    end
+
+    PushImage = PUSH_IMAGE_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/recreate_container.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for recreating Docker containers.
+    #
+    # This tool provides a complete container recreation process that stops
+    # the existing container, removes it, and creates a new container with
+    # the same configuration. This is useful for applying image updates,
+    # clearing container state, or resolving container corruption issues.
+    #
+    # == Features
+    #
+    # - Complete container recreation with preserved configuration
+    # - Automatic stop, remove, and recreate sequence
+    # - Preserves original container configuration and settings
+    # - Configurable stop timeout for graceful shutdown
+    # - Handles both running and stopped containers
+    # - Maintains container networking and volume configurations
+    #
+    # == Security Considerations
+    #
+    # Container recreation involves several security considerations:
+    # - **Service Downtime**: Temporary service interruption during recreation
+    # - **Data Loss**: Container file system changes are lost (volumes preserved)
+    # - **Resource Allocation**: New container may have different resource usage
+    # - **Network Reconfiguration**: IP addresses may change
+    # - **State Reset**: Application state within container is lost
+    #
+    # Plan recreations carefully and coordinate with dependent services.
+    #
+    # == Parameters
+    #
+    # - **id**: Container ID or name to recreate (required)
+    # - **timeout**: Seconds to wait before killing container when stopping (optional, default: 10)
+    #
+    # == Process Flow
+    #
+    # 1. Inspect existing container to capture configuration
+    # 2. Stop the running container (if running)
+    # 3. Remove the stopped container
+    # 4. Create new container with captured configuration
+    # 5. Return new container information
+    #
+    # == Example Usage
+    #
+    #   # Recreate with default timeout
+    #   response = RecreateContainer.call(
+    #     server_context: context,
+    #     id: "web-server"
+    #   )
+    #
+    #   # Recreate with extended timeout
+    #   response = RecreateContainer.call(
+    #     server_context: context,
+    #     id: "database",
+    #     timeout: 30
+    #   )
+    #
+    # @see ::Docker::Container#stop
+    # @see ::Docker::Container#remove
+    # @see ::Docker::Container.create
+    # @since 0.1.0
+    RECREATE_CONTAINER_DEFINITION = ToolForge.define(:recreate_container) do
+      description 'Recreate a Docker container (stops, removes, and recreates with same configuration)'
+
+      param :id,
+            type: :string,
+            description: 'Container ID or name to recreate'
+
+      param :timeout,
+            type: :integer,
+            description: 'Seconds to wait before killing the container when stopping (default: 10)',
+            required: false,
+            default: 10
+
+      execute do |id:, timeout: 10|
+        # Get the existing container
+        old_container = ::Docker::Container.get(id)
+        config = old_container.json
+
+        # Extract configuration we need to preserve
+        image = config['Config']['Image']
+        name = config['Name']&.delete_prefix('/')
+        cmd = config['Config']['Cmd']
+        env = config['Config']['Env']
+        exposed_ports = config['Config']['ExposedPorts']
+        host_config = config['HostConfig']
+
+        # Stop and remove the old container
+        old_container.stop('timeout' => timeout) if config['State']['Running']
+        old_container.delete
+
+        # Create new container with same config
+        new_config = {
+          'Image' => image,
+          'Cmd' => cmd,
+          'Env' => env,
+          'ExposedPorts' => exposed_ports,
+          'HostConfig' => host_config
+        }
+        new_config['name'] = name if name
+
+        new_container = ::Docker::Container.create(new_config)
+
+        # Start if the old one was running
+        new_container.start if config['State']['Running']
+
+        "Container #{id} recreated successfully. New ID: #{new_container.id}"
+      rescue ::Docker::Error::NotFoundError
+        "Container #{id} not found"
+      rescue StandardError => e
+        "Error recreating container: #{e.message}"
+      end
+    end
+
+    RecreateContainer = RECREATE_CONTAINER_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/remove_container.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for removing Docker containers.
+    #
+    # This tool permanently removes a Docker container from the system,
+    # including its file system, configuration, and metadata. This is a
+    # destructive operation that cannot be undone. The container must
+    # be stopped before removal unless force is specified.
+    #
+    # == Features
+    #
+    # - Permanent container removal from system
+    # - Supports forced removal of running containers
+    # - Optional removal of associated volumes
+    # - Handles container identification by ID or name
+    # - Provides comprehensive error handling
+    # - Frees all associated system resources
+    #
+    # == Security Considerations
+    #
+    # Container removal is a destructive operation with implications:
+    # - **Data Loss**: Permanently destroys container file system
+    # - **Configuration Loss**: Removes container settings and metadata
+    # - **Service Disruption**: Eliminates containerized services
+    # - **Resource Recovery**: Frees storage, memory, and system resources
+    # - **Audit Trail**: May remove forensic evidence if needed
+    #
+    # Implement proper backup and approval workflows for production systems.
+    #
+    # == Parameters
+    #
+    # - **id**: Container ID or name (required)
+    #   - Accepts full container IDs
+    #   - Accepts short container IDs (first 12+ characters)
+    #   - Accepts custom container names
+    # - **force**: Force removal of running container (optional, default: false)
+    # - **volumes**: Remove associated volumes (optional, default: false)
+    #
+    # == Example Usage
+    #
+    #   # Remove stopped container
+    #   response = RemoveContainer.call(
+    #     server_context: context,
+    #     id: "old-web-server"
+    #   )
+    #
+    #   # Force remove running container with volumes
+    #   response = RemoveContainer.call(
+    #     server_context: context,
+    #     id: "problematic-container",
+    #     force: true,
+    #     volumes: true
+    #   )
+    #
+    # @see ::Docker::Container#remove
+    # @since 0.1.0
+    REMOVE_CONTAINER_DEFINITION = ToolForge.define(:remove_container) do
+      description 'Remove a Docker container'
+
+      param :id,
+            type: :string,
+            description: 'Container ID or name'
+
+      param :force,
+            type: :boolean,
+            description: 'Force removal of running container (default: false)',
+            required: false,
+            default: false
+
+      param :volumes,
+            type: :boolean,
+            description: 'Remove associated volumes (default: false)',
+            required: false,
+            default: false
+
+      execute do |id:, force: false, volumes: false|
+        container = ::Docker::Container.get(id)
+        container.delete(force: force, v: volumes)
+
+        "Container #{id} removed successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Container #{id} not found"
+      rescue StandardError => e
+        "Error removing container: #{e.message}"
+      end
+    end
+
+    RemoveContainer = REMOVE_CONTAINER_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/remove_image.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for removing Docker images.
+    #
+    # This tool provides the ability to delete Docker images from the
+    # local Docker daemon. It supports various removal options including
+    # forced removal and parent image cleanup management.
+    #
+    # == Features
+    #
+    # - Remove images by ID, name, or tag
+    # - Force removal of images in use
+    # - Control untagged parent image cleanup
+    # - Comprehensive error handling
+    # - Validation of image existence
+    # - Safe removal with dependency checking
+    #
+    # == Security Considerations
+    #
+    # Image removal involves important considerations:
+    # - **Data Loss**: Removed images cannot be recovered locally
+    # - **Service Disruption**: Removing images used by running containers
+    # - **Storage Cleanup**: Improper cleanup can leave orphaned layers
+    # - **Registry Impact**: Local removal doesn't affect registry copies
+    # - **Dependency Conflicts**: Force removal can break container dependencies
+    #
+    # **Security Recommendations**:
+    # - Verify image is not in use before removal
+    # - Use force option only when necessary
+    # - Consider impact on running containers
+    # - Backup important images before removal
+    # - Monitor disk space after removal operations
+    # - Implement image lifecycle policies
+    #
+    # == Parameters
+    #
+    # - **id**: Image ID, name, or name:tag (required)
+    # - **force**: Force removal of the image (optional, default: false)
+    # - **noprune**: Do not delete untagged parents (optional, default: false)
+    #
+    # == Example Usage
+    #
+    #   # Remove specific image
+    #   response = RemoveImage.call(
+    #     server_context: context,
+    #     id: "myapp:old-version"
+    #   )
+    #
+    #   # Force remove image in use
+    #   response = RemoveImage.call(
+    #     server_context: context,
+    #     id: "abc123def456",
+    #     force: true
+    #   )
+    #
+    #   # Remove without cleaning parent images
+    #   response = RemoveImage.call(
+    #     server_context: context,
+    #     id: "test-image:latest",
+    #     noprune: true
+    #   )
+    #
+    # @see ::Docker::Image#remove
+    # @since 0.1.0
+    REMOVE_IMAGE_DEFINITION = ToolForge.define(:remove_image) do
+      description 'Remove a Docker image'
+
+      param :id,
+            type: :string,
+            description: 'Image ID, name, or name:tag'
+
+      param :force,
+            type: :boolean,
+            description: 'Force removal of the image (default: false)',
+            required: false,
+            default: false
+
+      param :noprune,
+            type: :boolean,
+            description: 'Do not delete untagged parents (default: false)',
+            required: false,
+            default: false
+
+      execute do |id:, force: false, noprune: false|
+        image = ::Docker::Image.get(id)
+        image.remove(force: force, noprune: noprune)
+
+        "Image #{id} removed successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Image #{id} not found"
+      rescue StandardError => e
+        "Error removing image: #{e.message}"
+      end
+    end
+
+    RemoveImage = REMOVE_IMAGE_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/remove_network.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for removing Docker networks.
+    #
+    # 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 networks by ID or name
+    # - Validation of network existence
+    # - Comprehensive error handling
+    # - Prevention of removing networks in use
+    # - Safe cleanup of network resources
+    # - Network dependency checking
+    #
+    # == Security Considerations
+    #
+    # 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 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
+    #
+    # == Parameters
+    #
+    # - **id**: Network ID or name (required)
+    #
+    # == Example Usage
+    #
+    #   # Remove network by name
+    #   response = RemoveNetwork.call(
+    #     server_context: context,
+    #     id: "app-network"
+    #   )
+    #
+    #   # Remove network by ID
+    #   response = RemoveNetwork.call(
+    #     server_context: context,
+    #     id: "abc123def456"
+    #   )
+    #
+    #   # Clean up test networks
+    #   response = RemoveNetwork.call(
+    #     server_context: context,
+    #     id: "test-isolated-network"
+    #   )
+    #
+    # @see ::Docker::Network#delete
+    # @since 0.1.0
+    REMOVE_NETWORK_DEFINITION = ToolForge.define(:remove_network) do
+      description 'Remove a Docker network'
+
+      param :id,
+            type: :string,
+            description: 'Network ID or name'
+
+      execute do |id:|
+        network = ::Docker::Network.get(id)
+        network.delete
+
+        "Network #{id} removed successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Network #{id} not found"
+      rescue StandardError => e
+        "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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for removing Docker volumes.
+    #
+    # 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 volumes by name
+    # - Force removal of volumes in use
+    # - Validation of volume existence
+    # - Comprehensive error handling
+    # - Safe volume cleanup procedures
+    # - Prevention of accidental data loss
+    #
+    # == Security Considerations
+    #
+    # 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
+    #
+    # **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
+    #
+    # == Parameters
+    #
+    # - **name**: Volume name (required)
+    # - **force**: Force removal of the volume (optional, default: false)
+    #
+    # == Example Usage
+    #
+    #   # Remove unused volume
+    #   response = RemoveVolume.call(
+    #     server_context: context,
+    #     name: "old-app-data"
+    #   )
+    #
+    #   # Force remove volume in use
+    #   response = RemoveVolume.call(
+    #     server_context: context,
+    #     name: "stuck-volume",
+    #     force: true
+    #   )
+    #
+    #   # Clean up test volumes
+    #   response = RemoveVolume.call(
+    #     server_context: context,
+    #     name: "test-data-volume"
+    #   )
+    #
+    # @see ::Docker::Volume#remove
+    # @since 0.1.0
+    REMOVE_VOLUME_DEFINITION = ToolForge.define(:remove_volume) do
+      description 'Remove a Docker volume'
+
+      param :name,
+            type: :string,
+            description: 'Volume name'
+
+      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)
+
+        "Volume #{name} removed successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Volume #{name} not found"
+      rescue StandardError => e
+        "Error removing volume: #{e.message}"
+      end
+    end
+
+    RemoveVolume = REMOVE_VOLUME_DEFINITION.to_ruby_llm_tool
+  end
+end