ruby_llm-docker 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa62cc209279d8d55720d84a9f964ffac227e13f203f85b9819fabb8119d259c
-  data.tar.gz: 47c3524da952c650163286685515f8eab9dbe21f8e03865c6c20ae5c5f8860dc
+  metadata.gz: 17035d50b89aaa2e3cfd6409b1a827a3dc9d6e8cc6013e703105b1bce1d6a80e
+  data.tar.gz: aac7610a23113ca2b1cad98e1d7eaa88210d069cf7cf9eaedf28736c526b2599
 SHA512:
-  metadata.gz: aefbb193a31a8234556a20c03ec3cab0d51b85a85fd166f239780a6093d9cf37a30c05cead7de949562df00ed0fff31c98ff799f3f29cbb1e85970a2d7469a74
-  data.tar.gz: 773dbc0e553ca52c969f60f0ec4ef5067dda65ab7c23a96fd4c49dc80649ec316adff48886b29fd589adbd93c3bada7afaa75192ad9cc0e0ebed055bd939451b
+  metadata.gz: 152b3442d3130660f7aad1815a7d16918fe20c61a06579f7ab4815a97af25c49cb581c39103b5b08bcf352ad0052cd8e9c601b9e320e2a0606ba3a7ee5b096fa
+  data.tar.gz: 041ce68408938affab9523541f1adb283a6c279e69d3b8abdcc6842c47154da1d0441dcb8a44a05f71c1ed382e4624c5d3136d45f5340c17ed8e9b8a96533176

data/examples/docker_chat.rb

@@ -13,21 +13,30 @@
 #   export OPENAI_API_KEY='your-key-here'
 #   ruby examples/docker_chat.rb
 #
+# Debug mode:
+#   ruby examples/docker_chat.rb --debug        # Enable debug output
+#   DOCKER_CHAT_DEBUG=true ruby examples/docker_chat.rb   # Via environment variable
+#
 # Commands:
 #   /exit      - Exit the chat
 #   /help      - Show available Docker tools
 #   /tools     - List all loaded tools
 #   /clear     - Clear the screen
+#   /debug     - Toggle debug mode on/off
 #   anything else - Send to OpenAI with Docker tools available
 
 require_relative '../lib/ruby_llm/docker'
 require 'io/console'
 
 # rubocop:disable Metrics/ClassLength
+
+# Interactive Docker chat interface using RubyLLM and OpenAI.
+# Provides natural language interaction with Docker containers, images, networks, and volumes.
 class DockerChat
   def initialize
     check_environment
     configure_ruby_llm
+    setup_debug_mode
     setup_chat
     @running = true
   end
@@ -54,8 +63,29 @@ class DockerChat
     end
   end
 
+  def setup_debug_mode
+    # Check for debug mode via environment variable or command line argument
+    @debug_mode = ENV['DOCKER_CHAT_DEBUG'] == 'true' || ARGV.include?('--debug') || ARGV.include?('-d')
+    debug_puts '🐛 Debug mode enabled' if @debug_mode
+  end
+
+  def debug_puts(message)
+    puts message if @debug_mode
+  end
+
   def setup_chat
+    # rubocop:disable Layout/BlockAlignment
+    # rubocop:disable Style/MultilineBlockChain
     @chat = RubyLLM.chat(model: 'gpt-4')
+                   .on_tool_call do |tool_call|
+                      debug_puts "🔧 Calling tool: #{tool_call.name}"
+                      debug_puts "📝 Arguments: #{tool_call.arguments}"
+                    end
+                    .on_tool_result do |result|
+                      debug_puts "✅ Tool returned: #{result}"
+                    end
+    # rubocop:enable Layout/BlockAlignment
+    # rubocop:enable Style/MultilineBlockChain
 
     # Add all Docker tools to the chat
     RubyLLM::Docker.add_all_tools_to_chat(@chat)
@@ -78,9 +108,11 @@ class DockerChat
     puts '  /help  - Show available Docker tools'
     puts '  /tools - List all loaded tools'
     puts '  /clear - Clear the screen'
+    puts '  /debug - Toggle debug mode on/off'
     puts
     puts '🚀 Ready! Type your questions or commands...'
     puts
+    debug_puts '🐛 Debug mode is currently enabled. Use /debug to toggle.'
   end
 
   def main_loop
@@ -118,6 +150,8 @@ class DockerChat
       show_tools
     when '/clear', '/c'
       clear_screen
+    when '/debug', '/d'
+      toggle_debug_mode
     when input.start_with?('/')
       puts "❓ Unknown command: #{input}"
       puts '   Type /help for available commands'
@@ -208,6 +242,13 @@ class DockerChat
     puts '🐳 Docker Chat - Screen cleared'
   end
 
+  def toggle_debug_mode
+    @debug_mode = !@debug_mode
+    status = @debug_mode ? 'enabled' : 'disabled'
+    puts "🐛 Debug mode #{status}"
+    debug_puts 'Debug output will now be shown for tool calls and results' if @debug_mode
+  end
+
   def show_goodbye
     puts "\n👋 Thanks for using Docker Chat!"
     puts '   Hope you found it helpful for managing your Docker environment.'

data/lib/ruby_llm/docker/build_image.rb

@@ -2,92 +2,90 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for building Docker images from Dockerfile content.
+    # MCP tool for building Docker images.
     #
-    # This tool provides the ability to build Docker images by providing Dockerfile
-    # content as a string. It supports optional tagging of the resulting image for
-    # easy identification and reuse.
+    # This tool provides the ability to build Docker images from Dockerfile
+    # content. It creates custom images by executing Dockerfile instructions
+    # and supports comprehensive build configuration including tagging and
+    # build arguments.
+    #
+    # == Features
+    #
+    # - Build images from Dockerfile content strings
+    # - Support for custom image tagging
+    # - Comprehensive build output and error reporting
+    # - Handles all standard Dockerfile instructions
+    # - Build context management
+    # - Progress tracking and logging
     #
     # == Security Considerations
     #
-    # Building Docker images can be potentially dangerous:
-    # - Dockerfile commands execute with Docker daemon privileges
-    # - Images can contain malicious software or backdoors
-    # - Build process can access host resources (network, files)
-    # - Base images may contain vulnerabilities
-    # - Build context may expose sensitive information
+    # Image building involves significant security risks:
+    # - **Code Execution**: Dockerfile RUN commands execute arbitrary code
+    # - **Network Access**: Build process can access networks and repositories
+    # - **File System Access**: Can read local files and directories
+    # - **Credential Exposure**: May expose build-time secrets and credentials
+    # - **Supply Chain Risk**: Downloaded packages may contain malware
+    # - **Resource Consumption**: Builds can consume significant CPU, memory, and storage
     #
-    # Security recommendations:
-    # - Review Dockerfile content carefully before building
-    # - Use trusted base images from official repositories
+    # **Security Recommendations**:
+    # - Review all Dockerfile content before building
+    # - Use trusted base images only
+    # - Avoid embedding secrets in image layers
+    # - Implement build isolation and sandboxing
+    # - Monitor build resource consumption
     # - Scan built images for vulnerabilities
-    # - Limit network access during builds
-    # - Avoid including secrets in Dockerfile instructions
-    # - Use multi-stage builds to minimize final image size
+    # - Use multi-stage builds to minimize attack surface
     #
-    # == Features
+    # == Parameters
     #
-    # - Build images from Dockerfile content strings
-    # - Optional image tagging during build
-    # - Comprehensive error handling
-    # - Support for all standard Dockerfile instructions
-    # - Returns image ID and build status
+    # - **dockerfile**: Dockerfile content as a string (required)
+    # - **tag**: Tag for the built image (optional, e.g., "myimage:latest")
     #
     # == Example Usage
     #
-    #   # Simple image build
-    #   BuildImage.call(
+    #   # Build simple image
+    #   dockerfile_content = <<~DOCKERFILE
+    #     FROM alpine:latest
+    #     RUN apk add --no-cache curl
+    #     CMD ["curl", "--version"]
+    #   DOCKERFILE
+    #
+    #   response = BuildImage.call(
     #     server_context: context,
-    #     dockerfile: "FROM alpine:latest\nRUN apk add --no-cache curl"
+    #     dockerfile: dockerfile_content,
+    #     tag: "my-curl:latest"
     #   )
     #
-    #   # Build with custom tag
-    #   BuildImage.call(
+    #   # Build web server image
+    #   dockerfile_content = <<~DOCKERFILE
+    #     FROM nginx:alpine
+    #     COPY nginx.conf /etc/nginx/nginx.conf
+    #     EXPOSE 80
+    #     CMD ["nginx", "-g", "daemon off;"]
+    #   DOCKERFILE
+    #
+    #   response = BuildImage.call(
     #     server_context: context,
     #     dockerfile: dockerfile_content,
-    #     tag: "myapp:v1.0"
+    #     tag: "custom-nginx:v1.0"
     #   )
     #
-    # @see Docker::Image.build
-    # @see TagImage
+    # @see ::Docker::Image.build_from_dir
     # @since 0.1.0
-    class BuildImage < RubyLLM::Tool
+    BUILD_IMAGE_DEFINITION = ToolForge.define(:build_image) do
       description 'Build a Docker image'
 
-      param :dockerfile, type: :string, desc: 'Dockerfile content as a string'
-      param :tag, type: :string, desc: 'Tag for the built image (e.g., "myimage:latest")', required: false
+      param :dockerfile,
+            type: :string,
+            description: 'Dockerfile content as a string'
 
-      # Build a Docker image from Dockerfile content.
-      #
-      # This method creates a Docker image by building from the provided Dockerfile
-      # content string. The Dockerfile is processed by the Docker daemon and can
-      # include any valid Dockerfile instructions. Optionally, the resulting image
-      # can be tagged with a custom name for easy reference.
-      #
-      # @param dockerfile [String] the complete Dockerfile content as a string
-      # @param server_context [Object] RubyLLM context (unused but required)
-      # @param tag [String, nil] optional tag to apply to the built image
-      #
-      # @return [RubyLLM::Tool::Response] build results including image ID and tag info
-      #
-      # @raise [Docker::Error] for Docker daemon communication errors
-      # @raise [StandardError] for build failures or other errors
-      #
-      # @example Build simple image
-      #   dockerfile = <<~DOCKERFILE
-      #     FROM alpine:latest
-      #     RUN apk add --no-cache nginx
-      #     EXPOSE 80
-      #     CMD ["nginx", "-g", "daemon off;"]
-      #   DOCKERFILE
-      #
-      #   response = tool.execute(
-      #     dockerfile: dockerfile,
-      #     tag: "my-nginx:latest"
-      #   )
-      #
-      # @see Docker::Image.build
-      def execute(dockerfile:, tag: nil)
+      param :tag,
+            type: :string,
+            description: 'Tag for the built image (e.g., "myimage:latest")',
+            required: false
+
+      execute do |dockerfile:, tag: nil|
         # Build the image
         image = ::Docker::Image.build(dockerfile)
 
@@ -101,11 +99,12 @@ module RubyLLM
 
         response_text = "Image built successfully. ID: #{image.id}"
         response_text += ", Tag: #{tag}" if tag
-
         response_text
       rescue StandardError => e
         "Error building image: #{e.message}"
       end
     end
+
+    BuildImage = BUILD_IMAGE_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/copy_to_container.rb

@@ -2,122 +2,124 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for copying files and directories from host to Docker containers.
+    # MCP tool for copying files and directories to Docker containers.
     #
-    # This tool provides the ability to copy files or entire directory trees from
-    # the host filesystem into running Docker containers. It uses Docker's archive
-    # streaming API to efficiently transfer files while preserving permissions and
-    # directory structure.
+    # This tool provides the ability to copy files and directories from the
+    # local host filesystem into running Docker containers. It supports both
+    # individual files and entire directory trees, with optional ownership
+    # modification within the container.
     #
-    # == ⚠️ SECURITY WARNING ⚠️
+    # == Features
     #
-    # This tool can be dangerous as it allows:
-    # - Reading arbitrary files from the host filesystem
-    # - Writing files into container filesystems
-    # - Potentially overwriting critical container files
-    # - Escalating privileges if used with setuid/setgid files
-    # - Exposing sensitive host data to containers
+    # - Copy files and directories from host to container
+    # - Supports recursive directory copying
+    # - Preserves file permissions and metadata
+    # - Optional ownership modification after copy
+    # - Works with running containers
+    # - Comprehensive error handling and validation
     #
-    # Security recommendations:
-    # - Validate source paths to prevent directory traversal
-    # - Ensure containers run with minimal privileges
-    # - Monitor file copy operations for sensitive paths
-    # - Use read-only filesystems where possible
-    # - Implement proper access controls on source files
+    # == Security Considerations
     #
-    # == Features
+    # File copying operations have significant security implications:
+    # - **File System Access**: Reads local host file system content
+    # - **Container Modification**: Alters container file system state
+    # - **Data Injection**: Can introduce malicious files into containers
+    # - **Permission Escalation**: May affect container security context
+    # - **Resource Consumption**: Large copies can consume storage and I/O
+    # - **Path Traversal**: Improper paths could access unintended locations
+    #
+    # **Security Recommendations**:
+    # - Validate and sanitize all file paths
+    # - Implement access controls for source file locations
+    # - Monitor file copy operations and sizes
+    # - Use read-only mounts where possible
+    # - Apply resource limits to prevent abuse
+    #
+    # == Parameters
     #
-    # - Copy individual files or entire directories
-    # - Preserve file permissions and directory structure
-    # - Optional ownership changes after copy
-    # - Comprehensive error handling
-    # - Support for both absolute and relative paths
+    # - **id**: Container ID or name (required)
+    # - **source_path**: Path to file/directory on local filesystem (required)
+    # - **destination_path**: Path inside container for copied content (required)
+    # - **owner**: Owner for copied files (optional, e.g., "1000:1000" or "username:group")
     #
     # == Example Usage
     #
-    #   # Copy a configuration file
-    #   CopyToContainer.call(
+    #   # Copy single file
+    #   response = CopyToContainer.call(
     #     server_context: context,
     #     id: "web-server",
-    #     source_path: "/host/config/nginx.conf",
-    #     destination_path: "/etc/nginx/"
+    #     source_path: "/local/config.conf",
+    #     destination_path: "/etc/nginx/nginx.conf"
     #   )
     #
     #   # Copy directory with ownership change
-    #   CopyToContainer.call(
+    #   response = CopyToContainer.call(
     #     server_context: context,
     #     id: "app-container",
-    #     source_path: "/host/app/src",
-    #     destination_path: "/app/",
-    #     owner: "appuser:appgroup"
+    #     source_path: "/local/app-data",
+    #     destination_path: "/var/lib/app",
+    #     owner: "app:app"
     #   )
     #
-    # @see Docker::Container#archive_in_stream
+    # @see ::Docker::Container#archive_in_stream
     # @since 0.1.0
-    class CopyToContainer < RubyLLM::Tool
+    COPY_TO_CONTAINER_DEFINITION = ToolForge.define(:copy_to_container) do
       description 'Copy a file or directory from the local filesystem into a running Docker container. ' \
                   'The source path is on the local machine, and the destination path is inside the container.'
 
-      param :id, type: :string, desc: 'Container ID or name'
-      param :source_path, type: :string, desc: 'Path to the file or directory on the local filesystem to copy'
-      param :destination_path, type: :string,
-                               desc: 'Path inside the container where the file/directory should be copied'
-      param :owner, type: :string,
-                    desc: 'Owner for the copied files (optional, e.g., "1000:1000" or "username:group")',
-                    required: false
-
-      # Copy files or directories from host filesystem to a Docker container.
-      #
-      # This method creates a tar archive of the source path and streams it into
-      # the specified container using Docker's archive API. The operation preserves
-      # file permissions and directory structure. Optionally, ownership can be
-      # changed after the copy operation completes.
-      #
-      # The source path must exist on the host filesystem and be readable by the
-      # process running the application. The destination path must be a valid path
-      # within the container.
-      #
-      # @param id [String] container ID or name to copy files into
-      # @param source_path [String] path to file/directory on host filesystem
-      # @param destination_path [String] destination path inside container
-      # @param server_context [Object] RubyLLM context (unused but required)
-      # @param owner [String, nil] ownership specification (e.g., "user:group", "1000:1000")
-      #
-      # @return [RubyLLM::Tool::Response] success/failure message with operation details
-      #
-      # @raise [Docker::Error::NotFoundError] if container doesn't exist
-      # @raise [StandardError] for file system or Docker API errors
-      #
-      # @example Copy configuration file
-      #   response = CopyToContainer.call(
-      #     server_context: context,
-      #     id: "nginx-container",
-      #     source_path: "/etc/nginx/sites-available/default",
-      #     destination_path: "/etc/nginx/sites-enabled/"
-      #   )
-      #
-      # @example Copy directory with ownership
-      #   response = tool.execute(
-      #     id: "app-container",
-      #     source_path: "/local/project",
-      #     destination_path: "/app/",
-      #     owner: "www-data:www-data"
-      #   )
-      #
-      # @see Docker::Container#archive_in_stream
-      # @see #add_to_tar
-      def execute(id:, source_path:, destination_path:, owner: nil)
+      param :id,
+            type: :string,
+            description: 'Container ID or name'
+
+      param :source_path,
+            type: :string,
+            description: 'Path to the file or directory on the local filesystem to copy'
+
+      param :destination_path,
+            type: :string,
+            description: 'Path inside the container where the file/directory should be copied'
+
+      param :owner,
+            type: :string,
+            description: 'Owner for the copied files (optional, e.g., "1000:1000" or "username:group")',
+            required: false
+
+      # Helper method for adding files/directories to tar
+      class_helper :add_to_tar do |tar, path, archive_path|
+        if File.directory?(path)
+          # Add directory entry
+          tar.mkdir(archive_path, File.stat(path).mode)
+
+          # Add directory contents
+          Dir.entries(path).each do |entry|
+            next if ['.', '..'].include?(entry)
+
+            full_path = File.join(path, entry)
+            archive_entry_path = File.join(archive_path, entry)
+            add_to_tar(tar, full_path, archive_entry_path)
+          end
+        else
+          # Add file
+          File.open(path, 'rb') do |file|
+            tar.add_file_simple(archive_path, File.stat(path).mode, file.size) do |tar_file|
+              IO.copy_stream(file, tar_file)
+            end
+          end
+        end
+      end
+
+      execute do |id:, source_path:, destination_path:, owner: nil|
         container = ::Docker::Container.get(id)
 
         # Verify source path exists
-        return "Source path not found: #{source_path}" unless File.exist?(source_path)
+        next "Source path not found: #{source_path}" unless File.exist?(source_path)
 
         # Create a tar archive of the source
         tar_io = StringIO.new
         tar_io.set_encoding('ASCII-8BIT')
 
         Gem::Package::TarWriter.new(tar_io) do |tar|
-          self.class.add_to_tar(tar, source_path, File.basename(source_path))
+          add_to_tar(tar, source_path, File.basename(source_path))
         end
 
         tar_io.rewind
@@ -136,61 +138,14 @@ module RubyLLM
         file_type = File.directory?(source_path) ? 'directory' : 'file'
         response_text = "Successfully copied #{file_type} from #{source_path} to #{id}:#{destination_path}"
         response_text += "\nOwnership changed to #{owner}" if owner
-
         response_text
       rescue ::Docker::Error::NotFoundError
         "Container #{id} not found"
       rescue StandardError => e
         "Error copying to container: #{e.message}"
       end
-
-      # Recursively add files and directories to a tar archive.
-      #
-      # This helper method builds a tar archive by recursively traversing
-      # the filesystem starting from the given path. It preserves file
-      # permissions and handles both files and directories appropriately.
-      #
-      # For directories, it creates directory entries in the tar and then
-      # recursively processes all contained files and subdirectories.
-      # For files, it reads the content and adds it to the tar with
-      # preserved permissions.
-      #
-      # @param tar [Gem::Package::TarWriter] the tar writer instance
-      # @param path [String] the filesystem path to add to the archive
-      # @param archive_path [String] the path within the tar archive
-      #
-      # @return [void]
-      #
-      # @example Add single file
-      #   add_to_tar(tar_writer, "/host/file.txt", "file.txt")
-      #
-      # @example Add directory tree
-      #   add_to_tar(tar_writer, "/host/mydir", "mydir")
-      #
-      # @see Gem::Package::TarWriter#mkdir
-      # @see Gem::Package::TarWriter#add_file_simple
-      def self.add_to_tar(tar, path, archive_path)
-        if File.directory?(path)
-          # Add directory entry
-          tar.mkdir(archive_path, File.stat(path).mode)
-
-          # Add directory contents
-          Dir.entries(path).each do |entry|
-            next if ['.', '..'].include?(entry)
-
-            full_path = File.join(path, entry)
-            archive_entry_path = File.join(archive_path, entry)
-            add_to_tar(tar, full_path, archive_entry_path)
-          end
-        else
-          # Add file
-          File.open(path, 'rb') do |file|
-            tar.add_file_simple(archive_path, File.stat(path).mode, file.size) do |tar_file|
-              IO.copy_stream(file, tar_file)
-            end
-          end
-        end
-      end
     end
+
+    CopyToContainer = COPY_TO_CONTAINER_DEFINITION.to_ruby_llm_tool
   end
 end