ruby_llm-docker 0.0.1 → 0.2.5

data/lib/ruby_llm/docker/list_volumes.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for listing Docker volumes.
+    #
+    # This tool provides functionality to list all Docker volumes on the system,
+    # including both named volumes and anonymous volumes. It returns comprehensive
+    # information about volume configuration, drivers, mount points, and usage.
+    #
+    # == Features
+    #
+    # - List all Docker volumes on the system
+    # - Comprehensive volume metadata
+    # - No configuration required
+    # - Read-only operation
+    # - Includes named and anonymous volumes
+    #
+    # == Volume Information Included
+    #
+    # The response typically includes:
+    # - **Volume Name**: Unique identifier for the volume
+    # - **Driver**: Volume driver (local, nfs, etc.)
+    # - **Mountpoint**: Physical location on host filesystem
+    # - **Labels**: User-defined metadata labels
+    # - **Options**: Driver-specific configuration options
+    # - **Scope**: Volume scope (local, global)
+    # - **CreatedAt**: Volume creation timestamp
+    #
+    # == Volume Types
+    #
+    # Docker manages different types of volumes:
+    # - **Named Volumes**: User-created persistent volumes
+    # - **Anonymous Volumes**: Automatically created temporary volumes
+    # - **Bind Mounts**: Direct host directory mounts (not shown in volume list)
+    # - **tmpfs Mounts**: Memory-based temporary filesystems (not shown)
+    #
+    # == Security Considerations
+    #
+    # This is a read-only operation that reveals storage information:
+    # - Exposes data storage architecture
+    # - Shows volume naming patterns
+    # - May reveal application data locations
+    # - Could aid in data discovery attacks
+    #
+    # While generally safe, consider access control:
+    # - Limit exposure of volume inventory
+    # - Be cautious with sensitive volume names
+    # - Monitor for unauthorized volume discovery
+    # - Consider data classification implications
+    #
+    # == Example Usage
+    #
+    #   # List all volumes
+    #   ListVolumes.call(server_context: context)
+    #
+    # @example Usage in data management
+    #   # Get available volumes before container creation
+    #   volumes_response = ListVolumes.call(server_context: context)
+    #   # Use volume information to select appropriate storage
+    #
+    # @see CreateVolume
+    # @see RemoveVolume
+    # @see Docker::Volume.all
+    # @since 0.1.0
+    class ListVolumes < RubyLLM::Tool
+      description 'List Docker volumes'
+
+      # List all Docker volumes available on the system.
+      #
+      # This method retrieves information about all Docker volumes, including
+      # both named volumes created by users and anonymous volumes created
+      # automatically by containers. The information includes comprehensive
+      # metadata for each volume.
+      #
+      # @return [String] comprehensive volume information
+      #
+      # @example List all volumes
+      #   response = tool.execute
+      #   # Returns detailed info for all Docker volumes
+      #
+      # @see Docker::Volume.all
+      def execute
+        ::Docker::Volume.all.map(&:info).to_s
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/pull_image.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for pulling Docker images from registries.
+    #
+    # This tool provides the ability to download Docker images from Docker
+    # registries (like Docker Hub) to the local system. It supports flexible
+    # tag specification and handles various image naming conventions.
+    #
+    # == Features
+    #
+    # - Pull images from any accessible Docker registry
+    # - Flexible tag specification (explicit or default)
+    # - Support for official and user repositories
+    # - Automatic latest tag handling
+    # - Comprehensive error handling
+    # - Progress tracking through Docker daemon
+    #
+    # == Security Considerations
+    #
+    # Pulling images can introduce security risks:
+    # - **Malicious Images**: Images may contain malware or backdoors
+    # - **Vulnerable Software**: Images may have known security vulnerabilities
+    # - **Untrusted Sources**: Images from unknown publishers may be compromised
+    # - **Supply Chain Attacks**: Legitimate-looking images may be malicious
+    # - **Resource Consumption**: Large images can consume significant disk space
+    #
+    # Security recommendations:
+    # - Only pull images from trusted registries and publishers
+    # - Verify image signatures when available
+    # - Scan pulled images for vulnerabilities
+    # - Use specific tags rather than 'latest'
+    # - Monitor registry access and authentication
+    # - Regularly update and patch images
+    #
+    # == Tag Handling
+    #
+    # The tool handles tags intelligently:
+    # - If image includes tag (e.g., "nginx:1.21"), use as specified
+    # - If separate tag provided, append to image name
+    # - If no tag specified, default to "latest"
+    # - Supports all Docker tag conventions
+    #
+    # == Example Usage
+    #
+    #   # Pull latest version
+    #   PullImage.call(
+    #     server_context: context,
+    #     from_image: "nginx"
+    #   )
+    #
+    #   # Pull specific version
+    #   PullImage.call(
+    #     server_context: context,
+    #     from_image: "postgres:13"
+    #   )
+    #
+    #   # Pull with separate tag parameter
+    #   PullImage.call(
+    #     server_context: context,
+    #     from_image: "redis",
+    #     tag: "7-alpine"
+    #   )
+    #
+    # @see BuildImage
+    # @see ListImages
+    # @see Docker::Image.create
+    # @since 0.1.0
+    class PullImage < RubyLLM::Tool
+      description 'Pull a Docker image'
+
+      param :from_image, desc: 'Image name to pull (e.g., "ubuntu" or "ubuntu:22.04")'
+      param :tag, desc: 'Tag to pull (optional, defaults to "latest" if not specified in from_image)', required: false
+
+      # Pull a Docker image from a registry.
+      #
+      # This method downloads the specified image from a Docker registry to
+      # the local system. It handles tag resolution automatically and provides
+      # feedback on the pull operation status.
+      #
+      # @param from_image [String] image name (may include registry and tag)
+      # @param server_context [Object] RubyLLM context (unused but required)
+      # @param tag [String, nil] specific tag to pull (overrides tag in from_image)
+      #
+      # @return [RubyLLM::Tool::Response] pull operation results with image ID
+      #
+      # @raise [Docker::Error::NotFoundError] if image doesn't exist in registry
+      # @raise [StandardError] for network or authentication failures
+      #
+      # @example Pull official image
+      #   response = PullImage.call(
+      #     server_context: context,
+      #     from_image: "ubuntu:22.04"
+      #   )
+      #
+      # @example Pull from custom registry
+      #   response = PullImage.call(
+      #     server_context: context,
+      #     from_image: "registry.example.com/myapp",
+      #     tag: "v1.0"
+      #   )
+      #
+      # @see Docker::Image.create
+      def execute(from_image:, tag: nil)
+        # If tag is provided separately, append it to from_image
+        # If from_image already has a tag (contains :), use as-is
+        # Otherwise default to :latest
+        image_with_tag = if tag
+                           "#{from_image}:#{tag}"
+                         elsif from_image.include?(':')
+                           from_image
+                         else
+                           "#{from_image}:latest"
+                         end
+
+        image = ::Docker::Image.create('fromImage' => image_with_tag)
+
+        "Image #{image_with_tag} pulled successfully. ID: #{image.id}"
+      rescue ::Docker::Error::NotFoundError
+        "Image #{image_with_tag} not found"
+      rescue StandardError => e
+        "Error pulling image: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/push_image.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module RubyLLM
+  module Docker
+    # RubyLLM 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 uses the Docker CLI to leverage native credential handling and push
+    # capabilities.
+    #
+    # == Features
+    #
+    # - Push images to any accessible Docker registry
+    # - Flexible image and tag specification
+    # - Native Docker credential handling
+    # - Support for private registries
+    # - Comprehensive error handling
+    # - Validation of registry-compatible names
+    #
+    # == ⚠️ Security Considerations ⚠️
+    #
+    # Pushing images involves significant security risks:
+    # - **Credential Exposure**: Registry credentials may be exposed
+    # - **Data Exfiltration**: Images may contain sensitive application data
+    # - **Intellectual Property**: Source code and binaries may be exposed
+    # - **Supply Chain Risk**: Malicious actors could access pushed images
+    # - **Registry Access**: Unauthorized access to registry accounts
+    #
+    # Critical security measures:
+    # - Verify registry authentication and authorization
+    # - Scan images for secrets before pushing
+    # - Use private registries for sensitive applications
+    # - Implement image signing and verification
+    # - Monitor registry access and downloads
+    # - Regularly audit pushed image contents
+    #
+    # == Registry Requirements
+    #
+    # Images must be properly tagged for registry compatibility:
+    # - Include registry hostname for private registries
+    # - Include username/organization for Docker Hub
+    # - Examples: `username/myapp`, `registry.company.com/team/app`
+    # - Local image names (without `/`) cannot be pushed
+    #
+    # == Example Usage
+    #
+    #   # Push to Docker Hub
+    #   PushImage.call(
+    #     server_context: context,
+    #     name: "myusername/myapp",
+    #     tag: "v1.0"
+    #   )
+    #
+    #   # Push to private registry
+    #   PushImage.call(
+    #     server_context: context,
+    #     name: "registry.company.com/team/app",
+    #     tag: "latest"
+    #   )
+    #
+    #   # Push with full repo specification
+    #   PushImage.call(
+    #     server_context: context,
+    #     name: "myapp",
+    #     repo_tag: "myregistry.com/myuser/myapp:v2.0"
+    #   )
+    #
+    # @see PullImage
+    # @see TagImage
+    # @see BuildImage
+    # @since 0.1.0
+    class PushImage < RubyLLM::Tool
+      description 'Push a Docker image'
+
+      param :name, type: :string, desc: 'Image name or ID to push'
+      param :tag, type: :string, desc: 'Tag to push (optional, pushes all tags if not specified)',
+                  required: false
+      param :repo_tag, type: :string, desc: 'Full repo:tag to push (e.g., "registry/repo:tag") (optional)',
+                       required: false
+
+      # Push a Docker image to a registry.
+      #
+      # This method uploads the specified image to a Docker registry using
+      # the Docker CLI for native credential handling. The image must be
+      # properly tagged for registry compatibility.
+      #
+      # @param name [String] image name or ID to push
+      # @param server_context [Object] RubyLLM context (unused but required)
+      # @param tag [String, nil] specific tag to push
+      # @param repo_tag [String, nil] complete repository:tag specification
+      #
+      # @return [RubyLLM::Tool::Response] push operation results
+      #
+      # @raise [StandardError] for push failures or authentication issues
+      #
+      # @example Push tagged image to Docker Hub
+      #   response = PushImage.call(
+      #     server_context: context,
+      #     name: "myuser/webapp",
+      #     tag: "v1.2.3"
+      #   )
+      #
+      # @example Push to private registry
+      #   response = tool.execute(
+      #     name: "internal-registry.com/team/service",
+      #     tag: "latest"
+      #   )
+      #
+      # @see Docker::Image.get
+      def execute(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
+        # Images without a registry prefix will fail to push to Docker Hub
+        unless name.include?('/') || repo_tag&.include?('/')
+          error_msg = 'Error: Image name must include registry/username ' \
+                      "(e.g., 'username/#{name}'). Local images cannot be " \
+                      'pushed without a registry prefix.'
+          return error_msg
+        end
+
+        # Verify the image exists
+        begin
+          ::Docker::Image.get(image_identifier)
+        rescue ::Docker::Error::NotFoundError
+          return "Image #{image_identifier} not found"
+        end
+
+        # Use the Docker CLI to push the image
+        # This way we leverage Docker's native credential handling
+        push_target = repo_tag || image_identifier
+        _, stderr, status = Open3.capture3('docker', 'push', push_target)
+
+        if status.success?
+          "Image #{push_target} pushed successfully"
+        else
+          # Extract the error message from stderr
+          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
+  end
+end

data/lib/ruby_llm/docker/recreate_container.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for recreating Docker containers with the same configuration.
+    #
+    # 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.
+    #
+    # == 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
+    #
+    # == 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)
+    #
+    # == ⚠️ Data Loss Warning ⚠️
+    #
+    # **DESTRUCTIVE OPERATION - DATA LOSS POSSIBLE**
+    #
+    # 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
+    #
+    # == Security Considerations
+    #
+    # - Original configuration is preserved exactly
+    # - Sensitive environment variables are maintained
+    # - Port mappings and volume mounts are restored
+    # - Network access patterns remain the same
+    #
+    # Ensure original configuration is still secure:
+    # - Review exposed ports and volumes
+    # - Validate environment variables
+    # - Check image security updates
+    # - Verify network policies
+    #
+    # == Example Usage
+    #
+    #   # Recreate with default timeout
+    #   RecreateContainer.call(
+    #     server_context: context,
+    #     id: "web-server"
+    #   )
+    #
+    #   # Recreate with longer stop timeout
+    #   RecreateContainer.call(
+    #     server_context: context,
+    #     id: "database",
+    #     timeout: 30
+    #   )
+    #
+    # @see CreateContainer
+    # @see StopContainer
+    # @see RemoveContainer
+    # @see Docker::Container.create
+    # @since 0.1.0
+    class RecreateContainer < RubyLLM::Tool
+      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
+
+      # 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)
+        # 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
+  end
+end

data/lib/ruby_llm/docker/remove_container.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM 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.
+    #
+    # == Features
+    #
+    # - Remove stopped containers safely
+    # - Force removal of running containers
+    # - Optional removal of associated volumes
+    # - Comprehensive error handling
+    # - Works with containers by ID or name
+    #
+    # == Data Loss Warning
+    #
+    # ⚠️ **DESTRUCTIVE OPERATION** ⚠️
+    #
+    # 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
+    #
+    # == Security Considerations
+    #
+    # - 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
+    #
+    # Best practices:
+    # - Stop containers gracefully before removal
+    # - Backup important data before removing
+    # - Verify volume dependencies before volume removal
+    # - Use force removal only when necessary
+    #
+    # == Example Usage
+    #
+    #   # Remove stopped container
+    #   RemoveContainer.call(
+    #     server_context: context,
+    #     id: "old-container"
+    #   )
+    #
+    #   # Force remove running container with volumes
+    #   RemoveContainer.call(
+    #     server_context: context,
+    #     id: "problematic-container",
+    #     force: true,
+    #     volumes: true
+    #   )
+    #
+    # @see StopContainer
+    # @see CreateContainer
+    # @see Docker::Container#delete
+    # @since 0.1.0
+    class RemoveContainer < RubyLLM::Tool
+      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
+
+      # 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)
+        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
+  end
+end