ruby_llm-docker 0.2.5 → 0.3.0

data/lib/ruby_llm/docker/recreate_container.rb

@@ -2,113 +2,79 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for recreating Docker containers with the same configuration.
+    # MCP tool for recreating Docker containers.
     #
-    # This tool provides a convenient way to recreate containers while preserving
-    # their original configuration. It stops and removes the existing container,
-    # then creates a new one with identical settings. This is useful for applying
-    # image updates, clearing container state, or resolving container issues.
+    # 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
     #
-    # - Preserves complete container configuration
-    # - Maintains original name and settings
-    # - Handles running containers gracefully
-    # - Restores running state after recreation
-    # - Configurable stop timeout
-    # - Comprehensive error handling
+    # - 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
     #
-    # == Process Overview
-    #
-    # 1. Retrieve existing container configuration
-    # 2. Stop container gracefully (if running)
-    # 3. Remove the old container
-    # 4. Create new container with identical config
-    # 5. Start new container (if original was running)
+    # == Security Considerations
     #
-    # == ⚠️ Data Loss Warning ⚠️
+    # 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
     #
-    # **DESTRUCTIVE OPERATION - DATA LOSS POSSIBLE**
+    # Plan recreations carefully and coordinate with dependent services.
     #
-    # This operation can cause permanent data loss:
-    # - Container filesystem changes are lost
-    # - Temporary data and logs are deleted
-    # - Container state is reset completely
-    # - Network connections are interrupted
-    # - Anonymous volumes may be recreated empty
+    # == Parameters
     #
-    # == Security Considerations
+    # - **id**: Container ID or name to recreate (required)
+    # - **timeout**: Seconds to wait before killing container when stopping (optional, default: 10)
     #
-    # - Original configuration is preserved exactly
-    # - Sensitive environment variables are maintained
-    # - Port mappings and volume mounts are restored
-    # - Network access patterns remain the same
+    # == Process Flow
     #
-    # Ensure original configuration is still secure:
-    # - Review exposed ports and volumes
-    # - Validate environment variables
-    # - Check image security updates
-    # - Verify network policies
+    # 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
-    #   RecreateContainer.call(
+    #   response = RecreateContainer.call(
     #     server_context: context,
     #     id: "web-server"
     #   )
     #
-    #   # Recreate with longer stop timeout
-    #   RecreateContainer.call(
+    #   # Recreate with extended timeout
+    #   response = RecreateContainer.call(
     #     server_context: context,
     #     id: "database",
     #     timeout: 30
     #   )
     #
-    # @see CreateContainer
-    # @see StopContainer
-    # @see RemoveContainer
-    # @see Docker::Container.create
+    # @see ::Docker::Container#stop
+    # @see ::Docker::Container#remove
+    # @see ::Docker::Container.create
     # @since 0.1.0
-    class RecreateContainer < RubyLLM::Tool
+    RECREATE_CONTAINER_DEFINITION = ToolForge.define(:recreate_container) do
       description 'Recreate a Docker container (stops, removes, and recreates with same configuration)'
 
-      param :id, type: :string, desc: 'Container ID or name to recreate'
-      param :timeout, type: :integer,
-                      desc: 'Seconds to wait before killing the container when stopping (default: 10)',
-                      required: false
+      param :id,
+            type: :string,
+            description: 'Container ID or name to recreate'
 
-      # Recreate a Docker container with identical configuration.
-      #
-      # This method performs a complete container recreation cycle while
-      # preserving all configuration settings. The new container will have
-      # the same name, environment, port mappings, volumes, and other
-      # settings as the original.
-      #
-      # @param id [String] container ID (full or short) or container name
-      # @param server_context [Object] RubyLLM context (unused but required)
-      # @param timeout [Integer] seconds to wait before force killing during stop (default: 10)
-      #
-      # @return [RubyLLM::Tool::Response] recreation results with new container ID
-      #
-      # @raise [Docker::Error::NotFoundError] if container doesn't exist
-      # @raise [StandardError] for recreation failures
-      #
-      # @example Recreate application container
-      #   response = RecreateContainer.call(
-      #     server_context: context,
-      #     id: "my-app"
-      #   )
-      #
-      # @example Recreate database with extended timeout
-      #   response = tool.execute(
-      #     id: "postgres-main",
-      #     timeout: 60  # Allow time for DB shutdown
-      #   )
-      #
-      # @see Docker::Container.get
-      # @see Docker::Container.create
-      def execute(id:, timeout: 10)
+      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
@@ -147,5 +113,7 @@ module RubyLLM
         "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

@@ -2,110 +2,80 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for removing Docker containers.
+    # MCP tool for removing Docker containers.
     #
-    # This tool provides the ability to permanently delete Docker containers
-    # from the system. It supports both graceful removal of stopped containers
-    # and forced removal of running containers. Optionally, it can also remove
-    # associated anonymous volumes.
+    # 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
     #
-    # - Remove stopped containers safely
-    # - Force removal of running containers
+    # - Permanent container removal from system
+    # - Supports forced removal of running containers
     # - Optional removal of associated volumes
-    # - Comprehensive error handling
-    # - Works with containers by ID or name
+    # - Handles container identification by ID or name
+    # - Provides comprehensive error handling
+    # - Frees all associated system resources
     #
-    # == Data Loss Warning
-    #
-    # ⚠️ **DESTRUCTIVE OPERATION** ⚠️
+    # == Security Considerations
     #
-    # This operation permanently deletes containers and potentially data:
-    # - Container filesystem changes are lost forever
-    # - Running processes are killed immediately (with force)
-    # - Associated volumes may be removed if specified
-    # - Container logs and metadata are deleted
-    # - Operation cannot be undone
+    # 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
     #
-    # == Security Considerations
+    # Implement proper backup and approval workflows for production systems.
     #
-    # - Forced removal can cause data corruption
-    # - Volume removal may affect other containers
-    # - Running container removal terminates services abruptly
-    # - Sensitive data in container memory is not securely wiped
+    # == Parameters
     #
-    # Best practices:
-    # - Stop containers gracefully before removal
-    # - Backup important data before removing
-    # - Verify volume dependencies before volume removal
-    # - Use force removal only when necessary
+    # - **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
-    #   RemoveContainer.call(
+    #   response = RemoveContainer.call(
     #     server_context: context,
-    #     id: "old-container"
+    #     id: "old-web-server"
     #   )
     #
     #   # Force remove running container with volumes
-    #   RemoveContainer.call(
+    #   response = RemoveContainer.call(
     #     server_context: context,
     #     id: "problematic-container",
     #     force: true,
     #     volumes: true
     #   )
     #
-    # @see StopContainer
-    # @see CreateContainer
-    # @see Docker::Container#delete
+    # @see ::Docker::Container#remove
     # @since 0.1.0
-    class RemoveContainer < RubyLLM::Tool
+    REMOVE_CONTAINER_DEFINITION = ToolForge.define(:remove_container) do
       description 'Remove a Docker container'
 
-      param :id, desc: 'Container ID or name'
-      param :force, type: :boolean, desc: 'Force removal of running container (default: false)', required: false
-      param :volumes, type: :boolean, desc: 'Remove associated volumes (default: false)', required: false
+      param :id,
+            type: :string,
+            description: 'Container ID or name'
 
-      # Remove a Docker container permanently.
-      #
-      # This method deletes a container from the Docker system. By default,
-      # it only removes stopped containers. The force option allows removal
-      # of running containers, and the volumes option removes associated
-      # anonymous volumes.
-      #
-      # @param id [String] container ID (full or short) or container name
-      # @param server_context [Object] RubyLLM context (unused but required)
-      # @param force [Boolean] whether to force remove running containers (default: false)
-      # @param volumes [Boolean] whether to remove associated volumes (default: false)
-      #
-      # @return [RubyLLM::Tool::Response] removal operation results
-      #
-      # @raise [Docker::Error::NotFoundError] if container doesn't exist
-      # @raise [StandardError] for other removal failures
-      #
-      # @example Remove stopped container
-      #   response = RemoveContainer.call(
-      #     server_context: context,
-      #     id: "finished-job"
-      #   )
-      #
-      # @example Force remove running container
-      #   response = RemoveContainer.call(
-      #     server_context: context,
-      #     id: "stuck-container",
-      #     force: true
-      #   )
-      #
-      # @example Remove container and its volumes
-      #   response = tool.execute(
-      #     id: "temp-container",
-      #     volumes: true
-      #   )
-      #
-      # @see Docker::Container#delete
-      def execute(id:, force: false, volumes: false)
+      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)
 
@@ -116,5 +86,7 @@ module RubyLLM
         "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

@@ -2,132 +2,88 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for removing Docker images.
+    # MCP tool for removing Docker images.
     #
-    # This tool provides the ability to permanently delete Docker images from
-    # the local system to free up disk space and remove unused images. It
-    # supports both regular and forced removal with options for parent image
-    # handling.
+    # 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 name:tag
+    # - Remove images by ID, name, or tag
     # - Force removal of images in use
-    # - Control parent image cleanup
+    # - Control untagged parent image cleanup
     # - Comprehensive error handling
+    # - Validation of image existence
     # - Safe removal with dependency checking
     #
-    # == ⚠️ Data Loss Warning ⚠️
-    #
-    # **DESTRUCTIVE OPERATION - PERMANENT DATA LOSS**
-    #
-    # This operation permanently deletes images and associated data:
-    # - Image layers are deleted from disk
-    # - All tags pointing to the image are removed
-    # - Operation cannot be undone
-    # - Dependent containers may become unusable
-    # - Custom modifications to images are lost
-    #
-    # == Dependency Management
-    #
-    # Docker images have complex dependency relationships:
-    # - **Child Images**: Images built FROM this image
-    # - **Parent Images**: Base images this image depends on
-    # - **Running Containers**: Containers using this image
-    # - **Stopped Containers**: Containers that could be restarted
-    #
     # == Security Considerations
     #
-    # Image removal affects system security posture:
-    # - Removes potentially vulnerable software
-    # - May break running applications
-    # - Could remove security patches
-    # - Affects rollback capabilities
-    #
-    # Best practices:
-    # - Verify no critical containers depend on the image
+    # 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
-    # - Use force removal judiciously
-    # - Monitor disk space after removal
-    # - Maintain image inventory documentation
+    # - Monitor disk space after removal operations
+    # - Implement image lifecycle policies
     #
-    # == Removal Options
+    # == Parameters
     #
-    # - **Normal Removal**: Only removes if no containers use the image
-    # - **Force Removal**: Removes even if containers depend on it
-    # - **Prune Parents**: Automatically removes unused parent images
-    # - **No Prune**: Keeps parent images even if unused
+    # - **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
     #
-    #   # Safe removal of unused image
-    #   RemoveImage.call(
+    #   # Remove specific image
+    #   response = RemoveImage.call(
     #     server_context: context,
-    #     id: "old-app:v1.0"
+    #     id: "myapp:old-version"
     #   )
     #
-    #   # Force removal of image in use
-    #   RemoveImage.call(
+    #   # Force remove image in use
+    #   response = RemoveImage.call(
     #     server_context: context,
-    #     id: "broken-image:latest",
+    #     id: "abc123def456",
     #     force: true
     #   )
     #
-    #   # Remove image but keep parent layers
-    #   RemoveImage.call(
+    #   # Remove without cleaning parent images
+    #   response = RemoveImage.call(
     #     server_context: context,
-    #     id: "temp-build:abc123",
+    #     id: "test-image:latest",
     #     noprune: true
     #   )
     #
-    # @see ListImages
-    # @see BuildImage
-    # @see Docker::Image#remove
+    # @see ::Docker::Image#remove
     # @since 0.1.0
-    class RemoveImage < RubyLLM::Tool
+    REMOVE_IMAGE_DEFINITION = ToolForge.define(:remove_image) do
       description 'Remove a Docker image'
 
-      param :id, type: :string, desc: 'Image ID, name, or name:tag'
-      param :force, type: :boolean, desc: 'Force removal of the image (default: false)', required: false
-      param :noprune, type: :boolean, desc: 'Do not delete untagged parents (default: false)', required: false
+      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
 
-      # Remove a Docker image from the local system.
-      #
-      # This method permanently deletes the specified image from local storage.
-      # By default, it performs safety checks to prevent removal of images with
-      # dependent containers. Force removal bypasses these checks.
-      #
-      # @param id [String] image ID, name, or name:tag to remove
-      # @param server_context [Object] RubyLLM context (unused but required)
-      # @param force [Boolean] whether to force removal despite dependencies (default: false)
-      # @param noprune [Boolean] whether to preserve parent images (default: false)
-      #
-      # @return [RubyLLM::Tool::Response] removal operation results
-      #
-      # @raise [Docker::Error::NotFoundError] if image doesn't exist
-      # @raise [StandardError] for removal failures or dependency conflicts
-      #
-      # @example Remove unused image
-      #   response = RemoveImage.call(
-      #     server_context: context,
-      #     id: "old-version:1.0"
-      #   )
-      #
-      # @example Force remove problematic image
-      #   response = RemoveImage.call(
-      #     server_context: context,
-      #     id: "corrupted-image",
-      #     force: true
-      #   )
-      #
-      # @example Remove while preserving layers
-      #   response = tool.execute(
-      #     id: "temp-image:build-123",
-      #     noprune: true
-      #   )
-      #
-      # @see Docker::Image#remove
-      def execute(id:, force: false, noprune: 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)
 
@@ -138,5 +94,7 @@ module RubyLLM
         "Error removing image: #{e.message}"
       end
     end
+
+    RemoveImage = REMOVE_IMAGE_DEFINITION.to_ruby_llm_tool
   end
 end