ruby_llm-docker 0.2.5 → 0.3.0

data/lib/ruby_llm/docker/stop_container.rb

@@ -2,99 +2,71 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for stopping running Docker containers.
+    # MCP tool for stopping Docker containers.
     #
-    # This tool provides the ability to gracefully stop running Docker containers
-    # with configurable timeout handling. It sends a SIGTERM signal to the main
-    # process and waits for the specified timeout before forcibly killing the
-    # container with SIGKILL.
+    # This tool gracefully stops a running Docker container by sending a
+    # SIGTERM signal to the main process, allowing it to shut down cleanly.
+    # If the container doesn't stop within the specified timeout, it will
+    # be forcefully killed with SIGKILL.
     #
     # == Features
     #
     # - Graceful container shutdown with SIGTERM
-    # - Configurable timeout before force kill
-    # - Works with containers by ID or name
-    # - Comprehensive error handling
-    # - Safe for already stopped containers
-    #
-    # == Shutdown Process
-    #
-    # 1. Send SIGTERM to container's main process
-    # 2. Wait for graceful shutdown up to timeout
-    # 3. Send SIGKILL if container hasn't stopped
-    # 4. Return success when container is stopped
+    # - Configurable timeout for forced termination
+    # - Supports container identification by ID or name
+    # - Handles both running and already-stopped containers
+    # - Provides clear feedback on operation status
+    # - Preserves container and data integrity
     #
     # == Security Considerations
     #
     # Stopping containers affects service availability:
-    # - Services become unavailable immediately
-    # - Network connections are terminated
-    # - Data may be lost if not properly persisted
-    # - Dependent services may be affected
+    # - **Service Disruption**: Terminates running services and processes
+    # - **Data Integrity**: May interrupt ongoing operations
+    # - **Resource Release**: Frees CPU, memory, and network resources
+    # - **State Preservation**: Maintains container state for future restart
+    #
+    # Coordinate container stops with dependent services and users.
     #
-    # Best practices:
-    # - Ensure data persistence before stopping
-    # - Consider impact on dependent services
-    # - Use appropriate timeout for graceful shutdown
-    # - Monitor application logs during shutdown
+    # == Parameters
+    #
+    # - **id**: Container ID or name (required)
+    #   - Accepts full container IDs
+    #   - Accepts short container IDs (first 12+ characters)
+    #   - Accepts custom container names
+    # - **timeout**: Seconds to wait before killing container (optional, default: 10)
     #
     # == Example Usage
     #
-    #   # Stop with default timeout (10 seconds)
-    #   StopContainer.call(
+    #   # Stop with default timeout
+    #   response = StopContainer.call(
     #     server_context: context,
     #     id: "web-server"
     #   )
     #
     #   # Stop with custom timeout
-    #   StopContainer.call(
+    #   response = StopContainer.call(
     #     server_context: context,
     #     id: "database",
     #     timeout: 30
     #   )
     #
-    # @see StartContainer
-    # @see RemoveContainer
-    # @see Docker::Container#stop
+    # @see ::Docker::Container#stop
     # @since 0.1.0
-    class StopContainer < RubyLLM::Tool
+    STOP_CONTAINER_DEFINITION = ToolForge.define(:stop_container) do
       description 'Stop a Docker container'
 
-      param :id, desc: 'Container ID or name'
-      param :timeout, type: :integer, desc: 'Seconds to wait before killing the container (default: 10)',
-                      required: false
+      param :id,
+            type: :string,
+            description: 'Container ID or name'
+
+      param :timeout,
+            type: :integer,
+            description: 'Seconds to wait before killing the container (default: 10)',
+            required: false,
+            default: 10
 
-      # Stop a running Docker container gracefully.
-      #
-      # This method stops a container by sending SIGTERM to the main process
-      # and waiting for the specified timeout before sending SIGKILL. The
-      # operation is idempotent - stopping an already stopped container
-      # typically succeeds without error.
-      #
-      # @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 (default: 10)
-      #
-      # @return [RubyLLM::Tool::Response] stop operation results
-      #
-      # @raise [Docker::Error::NotFoundError] if container doesn't exist
-      # @raise [StandardError] for other stop failures
-      #
-      # @example Stop with default timeout
-      #   response = StopContainer.call(
-      #     server_context: context,
-      #     id: "nginx-server"
-      #   )
-      #
-      # @example Stop database with longer timeout
-      #   response = StopContainer.call(
-      #     server_context: context,
-      #     id: "postgres-db",
-      #     timeout: 60  # Allow more time for DB shutdown
-      #   )
-      #
-      # @see Docker::Container#stop
-      def execute(id:, timeout: 10)
+      execute do |id:, timeout: 10|
         container = ::Docker::Container.get(id)
         container.stop('timeout' => timeout)
 
@@ -105,5 +77,7 @@ module RubyLLM
         "Error stopping container: #{e.message}"
       end
     end
+
+    StopContainer = STOP_CONTAINER_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/tag_image.rb

@@ -2,128 +2,98 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for tagging Docker images.
+    # MCP tool for tagging Docker images.
     #
-    # This tool provides the ability to create new tags for existing Docker images,
-    # enabling better organization, versioning, and distribution of images. Tags
-    # are essential for image management and registry operations.
+    # This tool provides the ability to assign repository names and tags
+    # to Docker images. Tagging is essential for image organization,
+    # versioning, and distribution through Docker registries.
     #
     # == Features
     #
-    # - Tag images by ID or existing name
-    # - Support for repository and tag specification
+    # - Tag existing images with custom repository names
+    # - Support for version and environment tags
     # - Force tagging to overwrite existing tags
-    # - Registry-compatible tag formatting
-    # - Comprehensive error handling
-    # - Multiple tags per image support
-    #
-    # == Tag Management Benefits
-    #
-    # Proper tagging enables:
-    # - **Version Control**: Track different image versions
-    # - **Distribution**: Prepare images for registry push
-    # - **Organization**: Group related images logically
-    # - **Deployment**: Reference specific image versions
-    # - **Rollback**: Maintain previous versions for rollback
+    # - Registry-compatible naming conventions
+    # - Automatic tag defaulting to "latest"
+    # - Comprehensive error handling and validation
     #
     # == Security Considerations
     #
-    # Tagging affects image accessibility and distribution:
-    # - Tags determine registry push destinations
-    # - Overwriting tags can affect running containers
-    # - Registry-compatible tags expose images for distribution
-    # - Tag names may reveal application details
+    # Image tagging involves several security considerations:
+    # - **Registry Authentication**: Tags may trigger registry operations
+    # - **Namespace Conflicts**: Overwriting tags can affect other deployments
+    # - **Image Identity**: Improper tagging can lead to deployment confusion
+    # - **Version Management**: Incorrect tags can compromise CI/CD pipelines
+    # - **Registry Pollution**: Excessive tagging can clutter registries
     #
-    # Best practices:
-    # - Use descriptive but not sensitive tag names
-    # - Avoid overwriting production tags accidentally
-    # - Implement tag naming conventions
-    # - Regular cleanup of unused tags
-    # - Control access to critical tag operations
+    # **Security Recommendations**:
+    # - Use consistent naming conventions
+    # - Implement tag governance policies
+    # - Verify image identity before tagging
+    # - Avoid overwriting production tags
+    # - Use semantic versioning for releases
+    # - Monitor tag usage and lifecycle
     #
-    # == Tag Naming Conventions
+    # == Parameters
     #
-    # Recommended patterns:
-    # - **Semantic Versioning**: `v1.2.3`, `1.2.3-alpha`
-    # - **Environment Tags**: `prod`, `staging`, `dev`
-    # - **Feature Tags**: `feature-branch-name`
-    # - **Date Tags**: `2024-01-15`, `20240115`
-    # - **Commit Tags**: `sha-abc123def`
+    # - **id**: Image ID or current name:tag to tag (required)
+    # - **repo**: Repository name (required, e.g., "username/imagename" or "registry/username/imagename")
+    # - **tag**: Tag for the image (optional, default: "latest")
+    # - **force**: Force tag even if it already exists (optional, default: true)
     #
     # == Example Usage
     #
-    #   # Tag with version
-    #   TagImage.call(
+    #   # Tag image with version
+    #   response = TagImage.call(
     #     server_context: context,
-    #     id: "abc123def456",
-    #     repo: "myapp",
-    #     tag: "v1.0.0"
+    #     id: "myapp:dev",
+    #     repo: "myregistry/myapp",
+    #     tag: "v1.2.3"
     #   )
     #
-    #   # Tag for registry push
-    #   TagImage.call(
+    #   # Tag for production deployment
+    #   response = TagImage.call(
     #     server_context: context,
-    #     id: "myapp:latest",
-    #     repo: "myusername/myapp",
-    #     tag: "production"
+    #     id: "abc123def456",
+    #     repo: "production/webapp",
+    #     tag: "stable",
+    #     force: false
     #   )
     #
-    #   # Tag for private registry
-    #   TagImage.call(
+    #   # Tag with registry prefix
+    #   response = TagImage.call(
     #     server_context: context,
-    #     id: "webapp:dev",
-    #     repo: "registry.company.com/team/webapp",
-    #     tag: "v2.1.0"
+    #     id: "local-build:latest",
+    #     repo: "registry.company.com/team/service",
+    #     tag: "release-candidate"
     #   )
     #
-    # @see BuildImage
-    # @see PushImage
-    # @see Docker::Image#tag
+    # @see ::Docker::Image#tag
     # @since 0.1.0
-    class TagImage < RubyLLM::Tool
+    TAG_IMAGE_DEFINITION = ToolForge.define(:tag_image) do
       description 'Tag a Docker image'
 
-      param :id, type: :string, desc: 'Image ID or current name:tag'
-      param :repo, type: :string,
-                   desc: 'Repository name (e.g., "username/imagename" or "registry/username/imagename")'
-      param :tag, type: :string, desc: 'Tag for the image (default: "latest")', required: false
-      param :force, type: :boolean, desc: 'Force tag even if it already exists (default: true)', required: false
+      param :id,
+            type: :string,
+            description: 'Image ID or current name:tag to tag'
 
-      # Tag a Docker image with a new repository and tag name.
-      #
-      # This method creates a new tag for an existing image, allowing it to
-      # be referenced by the new name. This is essential for organizing images
-      # and preparing them for registry distribution.
-      #
-      # @param id [String] image ID or current name:tag to tag
-      # @param repo [String] repository name for the new tag
-      # @param server_context [Object] RubyLLM context (unused but required)
-      # @param tag [String] tag name for the image (default: "latest")
-      # @param force [Boolean] whether to overwrite existing tags (default: true)
-      #
-      # @return [RubyLLM::Tool::Response] tagging operation results
-      #
-      # @raise [Docker::Error::NotFoundError] if source image doesn't exist
-      # @raise [StandardError] for other tagging failures
-      #
-      # @example Tag for versioning
-      #   response = TagImage.call(
-      #     server_context: context,
-      #     id: "my-app:latest",
-      #     repo: "my-app",
-      #     tag: "v1.2.3"
-      #   )
-      #
-      # @example Tag for registry push
-      #   response = tool.execute(
-      #     id: "abc123def456",
-      #     repo: "myregistry.com/myuser/myapp",
-      #     tag: "production",
-      #     force: true
-      #   )
-      #
-      # @see Docker::Image#tag
-      def execute(id:, repo:, tag: 'latest', force: true)
+      param :repo,
+            type: :string,
+            description: 'Repository name (e.g., "username/imagename" or "registry/username/imagename")'
+
+      param :tag,
+            type: :string,
+            description: 'Tag for the image (default: "latest")',
+            required: false,
+            default: 'latest'
+
+      param :force,
+            type: :boolean,
+            description: 'Force tag even if it already exists (default: true)',
+            required: false,
+            default: true
+
+      execute do |id:, repo:, tag: 'latest', force: true|
         image = ::Docker::Image.get(id)
 
         image.tag('repo' => repo, 'tag' => tag, 'force' => force)
@@ -135,5 +105,7 @@ module RubyLLM
         "Error tagging image: #{e.message}"
       end
     end
+
+    TagImage = TAG_IMAGE_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/version.rb

@@ -2,6 +2,15 @@
 
 module RubyLLM
   module Docker
-    VERSION = '0.2.5'
+    # Current version of the RubyLLM::Docker gem.
+    #
+    # This constant follows semantic versioning (SemVer) principles:
+    # - MAJOR version for incompatible API changes
+    # - MINOR version for backwards-compatible functionality additions
+    # - PATCH version for backwards-compatible bug fixes
+    #
+    # @see https://semver.org/
+    # @since 0.1.0
+    VERSION = '0.3.0'
   end
 end

data/lib/ruby_llm/docker.rb

@@ -3,6 +3,7 @@
 require 'ruby_llm'
 require 'docker'
 require 'shellwords'
+require 'tool_forge'
 require 'zeitwerk'
 
 loader = Zeitwerk::Loader.for_gem_extension(RubyLLM)
@@ -11,6 +12,18 @@ loader.setup
 require_relative 'docker/version'
 
 module RubyLLM
+  # Docker tools module providing comprehensive Docker management capabilities for RubyLLM.
+  #
+  # This module contains 22 Docker management tools organized into four categories:
+  # - Container Management (10 tools)
+  # - Image Management (6 tools)
+  # - Network Management (3 tools)
+  # - Volume Management (3 tools)
+  #
+  # @example Basic usage
+  #   chat = RubyLLM::Chat.new(api_key: 'your-key', model: 'gpt-4')
+  #   RubyLLM::Docker.add_all_tools_to_chat(chat)
+  #   response = chat.ask("How many containers are running?")
   module Docker
     class Error < StandardError; end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-docker
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Aaron F Stanton
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: tool_forge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement