kamal-dev 0.3.0

data/lib/kamal/dev/builder.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Dev
+    # Builder for building and pushing Docker images
+    #
+    # Wraps Docker build and push operations with:
+    # - Build progress display
+    # - Tag management (timestamp, git SHA, custom)
+    # - Error handling for build failures
+    # - Registry authentication
+    #
+    # @example Build an image
+    #   builder = Kamal::Dev::Builder.new(config, registry)
+    #   builder.build(
+    #     dockerfile: ".devcontainer/Dockerfile",
+    #     context: ".",
+    #     tag: "abc123"
+    #   )
+    #
+    # @example Push an image
+    #   builder.push("myapp-dev:abc123")
+    #
+    class Builder
+      attr_reader :config, :registry
+
+      # Initialize builder with configuration and registry
+      #
+      # @param config [Kamal::Dev::Config] Configuration object
+      # @param registry [Kamal::Dev::Registry] Registry object
+      def initialize(config, registry)
+        @config = config
+        @registry = registry
+      end
+
+      # Build Docker image from Dockerfile
+      #
+      # @param dockerfile [String] Path to Dockerfile
+      # @param context [String] Build context path (default: ".")
+      # @param tag [String] Image tag (optional, auto-generated if not provided)
+      # @param image_base [String] Base image name from config (optional, uses config.service if not provided)
+      # @param build_args [Hash] Build arguments (optional)
+      # @param secrets [Hash] Build secrets (optional)
+      # @return [String] Full image reference with tag
+      # @raise [Kamal::Dev::BuildError] if build fails
+      def build(dockerfile:, context: ".", tag: nil, image_base: nil, build_args: {}, secrets: {})
+        tag ||= registry.tag_with_timestamp
+
+        # Use image_base if provided (new format), otherwise fall back to service name (old format)
+        image_ref = if image_base
+          registry.image_tag(image_base, tag)
+        else
+          registry.image_tag(config.service, tag)
+        end
+
+        # If git clone is enabled, wrap Dockerfile with entrypoint injection
+        if config.git_clone_enabled?
+          build_with_entrypoint(
+            dockerfile: dockerfile,
+            context: context,
+            image: image_ref,
+            build_args: build_args,
+            secrets: secrets
+          )
+        else
+          command = build_command(
+            dockerfile: dockerfile,
+            context: context,
+            image: image_ref,
+            build_args: build_args,
+            secrets: secrets
+          )
+
+          execute_with_output(command, "Building image #{image_ref}...")
+        end
+
+        image_ref
+      end
+
+      # Push Docker image to registry
+      #
+      # @param image_ref [String] Full image reference (registry/user/image:tag)
+      # @return [Boolean] true if push succeeded
+      # @raise [Kamal::Dev::BuildError] if push fails
+      def push(image_ref)
+        command = ["docker", "push", image_ref]
+
+        execute_with_output(command, "Pushing image #{image_ref}...")
+
+        true
+      end
+
+      # Authenticate with Docker registry
+      #
+      # @return [Boolean] true if login succeeded
+      # @raise [Kamal::Dev::RegistryError] if login fails
+      def login
+        command = registry.login_command
+
+        # Login command uses password on command line, so we execute silently
+        result = execute_command(command)
+
+        unless result[:success]
+          raise Kamal::Dev::RegistryError,
+            "Docker login failed: #{result[:error]}"
+        end
+
+        true
+      end
+
+      # Check if Docker is available
+      #
+      # @return [Boolean] true if Docker is installed and running
+      def docker_available?
+        result = execute_command(["docker", "version"])
+        result[:success]
+      end
+
+      # Check if image exists locally
+      #
+      # @param image_ref [String] Full image reference
+      # @return [Boolean] true if image exists
+      def image_exists?(image_ref)
+        result = execute_command(["docker", "image", "inspect", image_ref])
+        result[:success]
+      end
+
+      # Tag image with timestamp
+      #
+      # @param base_image [String] Base image reference
+      # @return [String] New image reference with timestamp tag
+      def tag_with_timestamp(base_image)
+        tag = registry.tag_with_timestamp
+        new_image = "#{base_image}:#{tag}"
+
+        execute_command(["docker", "tag", base_image, new_image])
+
+        new_image
+      end
+
+      # Tag image with git SHA
+      #
+      # @param base_image [String] Base image reference
+      # @return [String, nil] New image reference with git SHA tag or nil if not in git repo
+      def tag_with_git_sha(base_image)
+        tag = registry.tag_with_git_sha
+        return nil unless tag
+
+        new_image = "#{base_image}:#{tag}"
+
+        execute_command(["docker", "tag", base_image, new_image])
+
+        new_image
+      end
+
+      private
+
+      # Build image with kamal-dev entrypoint injected
+      #
+      # Creates a temporary wrapper Dockerfile that:
+      # 1. Builds from the original Dockerfile
+      # 2. Injects the dev-entrypoint.sh script
+      # 3. Sets it as the container entrypoint
+      #
+      # @param dockerfile [String] Original Dockerfile path
+      # @param context [String] Build context
+      # @param image [String] Target image name with tag
+      # @param build_args [Hash] Build arguments
+      # @param secrets [Hash] Build secrets
+      def build_with_entrypoint(dockerfile:, context:, image:, build_args: {}, secrets: {})
+        require "tmpdir"
+        require "fileutils"
+
+        Dir.mktmpdir("kamal-dev-build") do |temp_dir|
+          # Copy entrypoint script to temp directory
+          entrypoint_template = File.expand_path("../templates/dev-entrypoint.sh", __FILE__)
+          entrypoint_dest = File.join(temp_dir, "dev-entrypoint.sh")
+          FileUtils.cp(entrypoint_template, entrypoint_dest)
+          FileUtils.chmod(0755, entrypoint_dest)
+
+          # Resolve paths to absolute
+          context_abs = File.expand_path(context)
+          original_dockerfile_path = File.expand_path(File.join(context, dockerfile))
+
+          # Create wrapper Dockerfile
+          wrapper_dockerfile = File.join(temp_dir, "Dockerfile.kamal-dev")
+          File.write(wrapper_dockerfile, generate_wrapper_dockerfile(original_dockerfile_path))
+
+          # Copy wrapper to context so docker build can access it
+          FileUtils.cp(wrapper_dockerfile, File.join(context_abs, "Dockerfile.kamal-dev"))
+          FileUtils.cp(entrypoint_dest, File.join(context_abs, "dev-entrypoint.sh"))
+
+          begin
+            # Build using wrapper Dockerfile
+            command = build_command(
+              dockerfile: "Dockerfile.kamal-dev",
+              context: context,
+              image: image,
+              build_args: build_args,
+              secrets: secrets
+            )
+
+            execute_with_output(command, "Building image with kamal-dev entrypoint #{image}...")
+          ensure
+            # Cleanup temporary files from context
+            FileUtils.rm_f(File.join(context_abs, "Dockerfile.kamal-dev"))
+            FileUtils.rm_f(File.join(context_abs, "dev-entrypoint.sh"))
+          end
+        end
+      end
+
+      # Generate wrapper Dockerfile content
+      #
+      # @param original_dockerfile [String] Path to original Dockerfile
+      # @return [String] Wrapper Dockerfile content
+      def generate_wrapper_dockerfile(original_dockerfile)
+        # Read original Dockerfile to extract final image
+        # Use multi-stage build: stage 1 = original, stage 2 = add entrypoint
+        <<~DOCKERFILE
+          # Stage 1: Build original image
+          FROM scratch AS original-dockerfile
+          # This is a placeholder - we'll build from the original file
+
+          # We can't easily include another Dockerfile, so we'll use a different approach
+          # Build the original image first, then extend it
+
+          # Actually, simpler approach: read the original and inline it
+        DOCKERFILE
+
+        # Better approach: Just extend the original Dockerfile directly
+        original_content = File.read(original_dockerfile)
+
+        <<~DOCKERFILE
+          #{original_content}
+
+          # Kamal Dev: Inject entrypoint for git clone functionality
+          # Create /workspaces directory with proper ownership for non-root user
+          USER root
+          RUN mkdir -p /workspaces && chown -R vscode:vscode /workspaces
+          USER vscode
+
+          # Copy entrypoint script with execute permissions
+          COPY --chmod=755 dev-entrypoint.sh /usr/local/bin/dev-entrypoint.sh
+          ENTRYPOINT ["/usr/local/bin/dev-entrypoint.sh"]
+        DOCKERFILE
+      end
+
+      # Build docker build command
+      #
+      # @param dockerfile [String] Dockerfile path
+      # @param context [String] Build context
+      # @param image [String] Image reference with tag
+      # @param build_args [Hash] Build arguments
+      # @param secrets [Hash] Build secrets
+      # @return [Array<String>] Docker build command
+      def build_command(dockerfile:, context:, image:, build_args: {}, secrets: {})
+        cmd = ["docker", "build"]
+
+        # Add platform flag for cross-platform compatibility
+        # Cloud VMs are typically linux/amd64, even when building on arm64 (Mac)
+        cmd += ["--platform", "linux/amd64"]
+
+        # Add dockerfile flag
+        cmd += ["-f", dockerfile] if dockerfile != "Dockerfile"
+
+        # Add tag
+        cmd += ["-t", image]
+
+        # Add build args
+        build_args.each do |key, value|
+          cmd += ["--build-arg", "#{key}=#{value}"]
+        end
+
+        # Add build secrets
+        secrets.each do |key, value|
+          cmd += ["--secret", "id=#{key},env=#{value}"]
+        end
+
+        # Add context (must be last)
+        cmd << context
+
+        cmd
+      end
+
+      # Execute command and capture output
+      #
+      # @param command [Array<String>] Command to execute
+      # @param message [String] Progress message to display
+      # @return [Hash] Result with :success, :output, :error
+      # @raise [Kamal::Dev::BuildError] if command fails
+      def execute_with_output(command, message)
+        puts message if message
+
+        result = execute_command(command, show_output: true)
+
+        unless result[:success]
+          raise Kamal::Dev::BuildError,
+            "Command failed: #{command.join(" ")}\n#{result[:error]}"
+        end
+
+        result
+      end
+
+      # Execute shell command
+      #
+      # @param command [Array<String>] Command to execute
+      # @param show_output [Boolean] Whether to show command output
+      # @return [Hash] Result with :success, :output, :error
+      def execute_command(command, show_output: false)
+        require "open3"
+
+        output, error, status = Open3.capture3(*command)
+
+        if show_output && !output.empty?
+          puts output
+        end
+
+        {
+          success: status.success?,
+          output: output,
+          error: error
+        }
+      rescue => e
+        {
+          success: false,
+          output: "",
+          error: e.message
+        }
+      end
+    end
+  end
+end

data/lib/kamal/dev/compose_parser.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Kamal
+  module Dev
+    # Parser for Docker Compose files
+    #
+    # Parses compose.yaml files to extract service definitions, build contexts,
+    # and Dockerfiles. Identifies main application service vs dependent services
+    # (databases, caches, etc.) for deployment orchestration.
+    #
+    # @example Basic usage
+    #   parser = Kamal::Dev::ComposeParser.new(".devcontainer/compose.yaml")
+    #   parser.main_service
+    #   # => "app"
+    #
+    # @example Get build context
+    #   parser.service_build_context("app")
+    #   # => "."
+    #
+    # @example Check if service has build section
+    #   parser.has_build_section?("postgres")
+    #   # => false
+    #
+    class ComposeParser
+      attr_reader :compose_file_path, :compose_data
+
+      # Initialize parser with compose file path
+      #
+      # @param compose_file_path [String] Path to compose.yaml file
+      # @raise [Kamal::Dev::ConfigurationError] if file not found or invalid YAML
+      def initialize(compose_file_path)
+        @compose_file_path = compose_file_path
+        @compose_data = load_and_parse
+      end
+
+      # Get all services from compose file
+      #
+      # @return [Hash] Service definitions keyed by service name
+      def services
+        compose_data.fetch("services", {})
+      end
+
+      # Identify the main application service
+      #
+      # Uses heuristic: first service with a build: section,
+      # or first service if none have build sections
+      #
+      # @return [String, nil] Main service name
+      def main_service
+        # Find first service with build section
+        service_with_build = services.find { |_, config| config.key?("build") }
+        return service_with_build[0] if service_with_build
+
+        # Fallback to first service
+        services.keys.first
+      end
+
+      # Get build context for a service
+      #
+      # Resolves context path relative to the compose file's directory,
+      # since Docker Compose interprets paths relative to the compose file location.
+      #
+      # @param service_name [String] Service name
+      # @return [String] Build context path resolved relative to compose file (default: ".")
+      def service_build_context(service_name)
+        service = services[service_name]
+        return "." unless service
+
+        build_config = service["build"]
+        return "." unless build_config
+
+        # Get context from build config
+        context = if build_config.is_a?(String)
+          # Handle string build path (shorthand) - this is the context
+          build_config
+        else
+          # Handle object build config
+          build_config["context"] || "."
+        end
+
+        # Resolve context relative to compose file's directory
+        # Docker Compose does this automatically, but we're extracting values
+        compose_dir = File.dirname(compose_file_path)
+        File.expand_path(context, compose_dir)
+      end
+
+      # Get Dockerfile path for a service
+      #
+      # Returns path relative to the build context (as Docker expects),
+      # NOT resolved to absolute path.
+      #
+      # @param service_name [String] Service name
+      # @return [String] Dockerfile path relative to build context (default: "Dockerfile")
+      def service_dockerfile(service_name)
+        service = services[service_name]
+        return "Dockerfile" unless service
+
+        build_config = service["build"]
+        return "Dockerfile" unless build_config
+
+        # Handle object build config
+        return "Dockerfile" if build_config.is_a?(String)
+
+        # Return dockerfile path as-is (relative to build context)
+        build_config["dockerfile"] || "Dockerfile"
+      end
+
+      # Check if service has a build section
+      #
+      # @param service_name [String] Service name
+      # @return [Boolean] true if service uses build:, false if image:
+      def has_build_section?(service_name)
+        service = services[service_name]
+        return false unless service
+
+        service.key?("build")
+      end
+
+      # Get dependent services (services without build sections)
+      #
+      # These are typically databases, caches, message queues, etc.
+      # that use pre-built images from registries
+      #
+      # @return [Array<String>] Service names without build sections
+      def dependent_services
+        services.select { |_, config| !config.key?("build") }.keys
+      end
+
+      # Transform compose file for deployment
+      #
+      # Replaces build: sections with image: references pointing to
+      # the pushed registry image. Removes local bind mounts (DevPod-style).
+      # Optionally injects git clone functionality for remote deployments.
+      # Preserves named volumes and other service properties.
+      #
+      # @param image_ref [String] Full image reference (e.g., "ghcr.io/user/app:tag")
+      # @param config [Kamal::Dev::Config] Optional config for git clone setup
+      # @return [String] Transformed YAML content
+      # @raise [Kamal::Dev::ConfigurationError] if transformation fails
+      def transform_for_deployment(image_ref, config: nil)
+        transformed = deep_copy(compose_data)
+        main = main_service
+
+        if main && transformed["services"][main]
+          # Remove build section
+          transformed["services"][main].delete("build")
+
+          # Add image reference
+          transformed["services"][main]["image"] = image_ref
+
+          # Remove local bind mounts (DevPod-style: code will be cloned, not mounted)
+          # Keep named volumes (databases, caches, etc.)
+          if transformed["services"][main]["volumes"]
+            transformed["services"][main]["volumes"] = transformed["services"][main]["volumes"].reject do |volume|
+              # Reject if it's a bind mount (contains ":" and first part is a path)
+              if volume.is_a?(String) && volume.include?(":")
+                source, _target = volume.split(":", 2)
+                # Named volumes don't start with . or / or ~
+                source.start_with?(".", "/", "~")
+              else
+                false
+              end
+            end
+
+            # Remove volumes array if empty
+            transformed["services"][main].delete("volumes") if transformed["services"][main]["volumes"].empty?
+          end
+
+          # Inject git clone environment variables if configured
+          # The actual cloning is handled by the entrypoint script in the image
+          if config&.git_clone_enabled?
+            inject_git_env_vars!(transformed["services"][main], config)
+          end
+        end
+
+        # Convert back to YAML
+        YAML.dump(transformed)
+      rescue => e
+        raise Kamal::Dev::ConfigurationError, "Failed to transform compose file: #{e.message}"
+      end
+
+      private
+
+      # Inject git clone environment variables into service configuration
+      #
+      # The entrypoint script in the Docker image will use these variables
+      # to clone the repository. Local devcontainers won't have these vars set,
+      # so they'll use mounted code instead.
+      #
+      # @param service_config [Hash] Service configuration to modify
+      # @param config [Kamal::Dev::Config] Configuration with git settings
+      def inject_git_env_vars!(service_config, config)
+        # Initialize environment hash if not present
+        service_config["environment"] ||= {}
+
+        # Inject git clone environment variables
+        # These are used by /usr/local/bin/dev-entrypoint.sh in the image
+        service_config["environment"]["KAMAL_DEV_GIT_REPO"] = config.git_repository
+        service_config["environment"]["KAMAL_DEV_GIT_BRANCH"] = config.git_branch
+        service_config["environment"]["KAMAL_DEV_WORKSPACE_FOLDER"] = config.git_workspace_folder
+
+        # Inject authentication token if configured (for private repositories)
+        if config.git_token
+          service_config["environment"]["KAMAL_DEV_GIT_TOKEN"] = config.git_token
+        end
+      end
+
+      # Load and parse compose YAML file
+      #
+      # @return [Hash] Parsed compose data
+      # @raise [Kamal::Dev::ConfigurationError] if file not found or invalid
+      def load_and_parse
+        unless File.exist?(compose_file_path)
+          raise Kamal::Dev::ConfigurationError, "Compose file not found: #{compose_file_path}"
+        end
+
+        content = File.read(compose_file_path)
+        data = YAML.safe_load(content, permitted_classes: [Symbol])
+
+        validate_compose_structure!(data)
+        data
+      rescue Psych::SyntaxError => e
+        raise Kamal::Dev::ConfigurationError, "Invalid YAML in compose file: #{e.message}"
+      end
+
+      # Validate compose file structure
+      #
+      # @param data [Hash] Parsed compose data
+      # @raise [Kamal::Dev::ConfigurationError] if structure invalid
+      def validate_compose_structure!(data)
+        unless data.is_a?(Hash)
+          raise Kamal::Dev::ConfigurationError, "Compose file must be a YAML object"
+        end
+
+        unless data.key?("services")
+          raise Kamal::Dev::ConfigurationError, "Compose file must have 'services' section"
+        end
+
+        if data["services"].empty?
+          raise Kamal::Dev::ConfigurationError, "Compose file must define at least one service"
+        end
+      end
+
+      # Deep copy hash to avoid modifying original
+      #
+      # @param obj [Object] Object to copy
+      # @return [Object] Deep copy
+      def deep_copy(obj)
+        Marshal.load(Marshal.dump(obj))
+      end
+    end
+  end
+end