kamal-dev 0.3.0

data/lib/kamal/dev/config.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "active_support/core_ext/hash"
+require_relative "devcontainer_parser"
+require_relative "devcontainer"
+require_relative "secrets_loader"
+
+module Kamal
+  module Dev
+    class Config
+      attr_reader :raw_config
+
+      def initialize(config, validate: false)
+        @raw_config = case config
+        when String
+          load_from_file(config)
+        when Hash
+          config.deep_symbolize_keys
+        else
+          raise Kamal::Dev::ConfigurationError, "Config must be a file path (String) or Hash"
+        end
+
+        validate! if validate
+      end
+
+      def service
+        raw_config[:service]
+      end
+
+      def image
+        raw_config[:image]
+      end
+
+      # Build configuration for building images from source
+      #
+      # @return [Hash] Build configuration (devcontainer, dockerfile, context)
+      def build
+        raw_config[:build]&.deep_stringify_keys || {}
+      end
+
+      # Check if build configuration is present
+      #
+      # @return [Boolean] true if build section exists
+      def build?
+        !build.empty?
+      end
+
+      # Get build source type
+      #
+      # @return [Symbol, nil] :devcontainer, :dockerfile, or nil
+      def build_source_type
+        return nil unless build?
+
+        if build["devcontainer"]
+          :devcontainer
+        elsif build["dockerfile"]
+          :dockerfile
+        end
+      end
+
+      # Get build source path (devcontainer.json or Dockerfile)
+      #
+      # @return [String, nil] Path to build source
+      def build_source_path
+        case build_source_type
+        when :devcontainer
+          build["devcontainer"]
+        when :dockerfile
+          build["dockerfile"]
+        end
+      end
+
+      # Get build context path
+      #
+      # @return [String] Build context (defaults to ".")
+      def build_context
+        build["context"] || "."
+      end
+
+      def provider
+        raw_config[:provider]&.deep_stringify_keys || {}
+      end
+
+      def defaults
+        raw_config[:defaults]&.deep_stringify_keys || {}
+      end
+
+      def vms
+        raw_config[:vms]&.deep_stringify_keys || {}
+      end
+
+      def vm_count
+        vms["count"] || 1
+      end
+
+      def naming_pattern
+        raw_config.dig(:naming, :pattern) || "{service}-{index}"
+      end
+
+      def secrets
+        raw_config[:secrets] || []
+      end
+
+      def secrets_file
+        raw_config[:secrets_file] || ".kamal/secrets"
+      end
+
+      def ssh
+        raw_config[:ssh]&.deep_stringify_keys || {}
+      end
+
+      def ssh_key_path
+        ssh["key_path"] || "~/.ssh/id_rsa.pub"
+      end
+
+      # Git configuration for remote code cloning
+      #
+      # @return [Hash] Git configuration (repository, branch, workspace_folder)
+      def git
+        raw_config[:git]&.deep_stringify_keys || {}
+      end
+
+      # Git repository URL to clone on remote deployment
+      #
+      # @return [String, nil] Git repository URL
+      def git_repository
+        git["repository"]
+      end
+
+      # Git branch to checkout (defaults to main)
+      #
+      # @return [String] Git branch name
+      def git_branch
+        git["branch"] || "main"
+      end
+
+      # Workspace folder where code should be cloned
+      # Typically matches the workspaceFolder in devcontainer.json
+      #
+      # @return [String] Workspace folder path
+      def git_workspace_folder
+        git["workspace_folder"] || "/workspaces/#{service}"
+      end
+
+      # Git authentication token (environment variable name)
+      # Used for HTTPS cloning of private repositories
+      #
+      # @return [String, nil] Environment variable name containing git token (e.g., GitHub PAT)
+      def git_token_env
+        git["token"]
+      end
+
+      # Git authentication token value loaded from environment
+      #
+      # @return [String, nil] Git token (GitHub PAT, GitLab token, etc.) from ENV
+      def git_token
+        return nil unless git_token_env
+        ENV[git_token_env]
+      end
+
+      # Check if git clone is configured for remote deployments
+      #
+      # @return [Boolean] true if git repository is configured
+      def git_clone_enabled?
+        !git_repository.nil? && !git_repository.empty?
+      end
+
+      # Registry configuration for image building and pushing
+      #
+      # @return [Hash] Registry configuration (server, username_env, password_env)
+      def registry
+        raw_config[:registry]&.deep_stringify_keys || {}
+      end
+
+      # Registry server URL (defaults to ghcr.io)
+      #
+      # @return [String] Registry server URL
+      def registry_server
+        registry["server"] || "ghcr.io"
+      end
+
+      # Registry username loaded from environment variable
+      #
+      # @return [String, nil] Registry username from ENV
+      def registry_username
+        return nil unless registry["username"]
+
+        # Handle both string and array formats (YAML parsing inconsistency)
+        env_var = registry["username"]
+        env_var = env_var.first if env_var.is_a?(Array)
+        ENV[env_var]
+      end
+
+      # Registry password/token loaded from environment variable
+      #
+      # @return [String, nil] Registry password from ENV
+      def registry_password
+        return nil unless registry["password"]
+
+        # Handle both string and array formats (YAML parsing inconsistency)
+        env_var = registry["password"]
+        env_var = env_var.first if env_var.is_a?(Array)
+        ENV[env_var]
+      end
+
+      # Check if registry credentials are configured
+      #
+      # @return [Boolean] true if both username and password ENV vars are set
+      def registry_configured?
+        !!(registry["username"] && registry["password"])
+      end
+
+      def container_name(index)
+        pattern = naming_pattern
+
+        # Handle zero-padded indexes like {index:03}
+        pattern = pattern.gsub(/\{index:(\d+)\}/) do
+          format("%0#{$1}d", index)
+        end
+
+        # Replace standard placeholders
+        name = pattern.gsub("{service}", service.to_s)
+          .gsub("{index}", index.to_s)
+
+        validate_docker_name!(name)
+        name
+      end
+
+      # Load and parse devcontainer configuration
+      #
+      # Handles both:
+      # - Direct image reference: image: "ruby:3.2"
+      # - Devcontainer.json path: image: ".devcontainer/devcontainer.json"
+      #
+      # @return [Devcontainer] Parsed devcontainer configuration
+      def devcontainer
+        @devcontainer ||= load_devcontainer
+      end
+
+      # Check if using devcontainer.json for configuration
+      #
+      # Supports both:
+      # - New format: build: { devcontainer: ".devcontainer/devcontainer.json" }
+      # - Old format: image: ".devcontainer/devcontainer.json" (backward compatibility)
+      #
+      # @return [Boolean] true if using devcontainer.json
+      def devcontainer_json?
+        # New format: build.devcontainer
+        return true if build_source_type == :devcontainer
+
+        # Old format: image points to .json file (backward compatibility)
+        image.to_s.end_with?(".json") || image.to_s.include?("devcontainer")
+      end
+
+      def validate!
+        errors = []
+
+        errors << "Configuration must include 'service' (service name is required)" if service.nil? || service.empty?
+        errors << "Configuration must include 'image' (image reference is required)" if image.nil? || image.empty?
+
+        if provider.empty?
+          errors << "Configuration must include 'provider' (provider configuration is required)"
+        elsif provider["type"].nil? || provider["type"].empty?
+          errors << "Configuration must include 'provider.type' (provider type is required)"
+        end
+
+        # Validate service name against Docker naming rules
+        unless service.nil? || service.empty?
+          unless docker_name_valid?(service)
+            errors << "Service name '#{service}' is invalid. Docker names must start with a letter or number and contain only [a-zA-Z0-9_.-]"
+          end
+        end
+
+        raise Kamal::Dev::ConfigurationError, errors.join("\n") unless errors.empty?
+
+        self
+      end
+
+      private
+
+      def load_from_file(path)
+        unless File.exist?(path)
+          raise Kamal::Dev::ConfigurationError, "Configuration file not found: #{path}"
+        end
+
+        YAML.safe_load_file(path, permitted_classes: [Symbol], symbolize_names: true)
+      rescue Psych::SyntaxError => e
+        raise Kamal::Dev::ConfigurationError, "Invalid YAML in #{path}: #{e.message}"
+      end
+
+      # Load devcontainer configuration
+      #
+      # Supports:
+      # - New format: build.devcontainer
+      # - Old format: image pointing to .json (backward compatibility)
+      # - Direct image reference
+      #
+      # @return [Devcontainer] Devcontainer instance
+      def load_devcontainer
+        config_hash = if devcontainer_json?
+          # Parse devcontainer.json file
+          # New format: build.devcontainer, Old format: image
+          devcontainer_path = build_source_path || image
+          parser = DevcontainerParser.new(devcontainer_path)
+          parser.parse
+        else
+          # Direct image reference - create minimal config
+          {
+            image: image,
+            ports: [],
+            mounts: [],
+            env: {},
+            options: [],
+            user: nil,
+            workspace: nil
+          }
+        end
+
+        # Load and inject secrets if configured
+        if !secrets.empty? && File.exist?(secrets_file)
+          loader = Kamal::Dev::SecretsLoader.new(secrets_file)
+          loaded_secrets = loader.load_secrets_for(secrets)
+          config_hash[:secrets] = loaded_secrets
+        else
+          config_hash[:secrets] = {}
+        end
+
+        Devcontainer.new(config_hash)
+      end
+
+      # Validate Docker name against naming rules
+      #
+      # Docker container names must:
+      # - Start with a letter or number
+      # - Contain only: letters, numbers, underscores, periods, hyphens
+      #
+      # @param name [String] Container name to validate
+      # @return [Boolean] true if valid, false otherwise
+      def docker_name_valid?(name)
+        return false if name.nil? || name.empty?
+
+        # Must start with alphanumeric and contain only [a-zA-Z0-9_.-]
+        name.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]*\z/)
+      end
+
+      # Validate and raise error if Docker name is invalid
+      #
+      # @param name [String] Container name to validate
+      # @raise [Kamal::Dev::ConfigurationError] if name is invalid
+      def validate_docker_name!(name)
+        return if docker_name_valid?(name)
+
+        raise Kamal::Dev::ConfigurationError,
+          "Container name '#{name}' is invalid. Docker names must start with a letter or number and contain only [a-zA-Z0-9_.-]"
+      end
+    end
+  end
+end

data/lib/kamal/dev/devcontainer.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Dev
+    # Represents a single devcontainer instance with its parsed configuration
+    #
+    # Provides methods to access Docker configuration and generate Docker run commands.
+    #
+    # @example Creating a devcontainer
+    #   config = {
+    #     image: "ruby:3.2",
+    #     ports: [3000, 5432],
+    #     mounts: [{source: "gem-cache", target: "/usr/local/bundle", type: "volume"}],
+    #     env: {"RAILS_ENV" => "development"},
+    #     options: ["--cpus=2", "--memory=4g"],
+    #     user: "vscode",
+    #     workspace: "/workspace"
+    #   }
+    #   devcontainer = Devcontainer.new(config)
+    #   command = devcontainer.docker_run_command(name: "myapp-dev-1")
+    class Devcontainer
+      attr_reader :image, :ports, :mounts, :env, :options, :user, :workspace, :secrets
+
+      # Initialize devcontainer with parsed configuration
+      #
+      # @param config [Hash] Parsed configuration hash with keys:
+      #   - :image [String] Docker image name
+      #   - :ports [Array<Integer>] Port mappings
+      #   - :mounts [Array<Hash>] Volume/bind mounts
+      #   - :env [Hash] Environment variables
+      #   - :options [Array<String>] Docker run options
+      #   - :user [String, nil] Remote user
+      #   - :workspace [String, nil] Workspace folder path
+      #   - :secrets [Hash, nil] Base64-encoded secrets (optional)
+      def initialize(config)
+        @image = config[:image]
+        @ports = config[:ports] || []
+        @mounts = config[:mounts] || []
+        @env = config[:env] || {}
+        @options = config[:options] || []
+        @user = config[:user]
+        @workspace = config[:workspace]
+        @secrets = config[:secrets] || {}
+      end
+
+      # Generate Docker run flags from configuration
+      #
+      # @return [Array<String>] Array of Docker flags and their values
+      def docker_run_flags
+        flags = []
+
+        # Port mappings (-p HOST:CONTAINER)
+        @ports.each do |port|
+          flags << "-p"
+          flags << "#{port}:#{port}"
+        end
+
+        # Volume mounts (-v SOURCE:TARGET)
+        @mounts.each do |mount|
+          flags << "-v"
+          flags << "#{mount[:source]}:#{mount[:target]}"
+        end
+
+        # Environment variables (-e KEY=VALUE)
+        @env.each do |key, value|
+          flags << "-e"
+          flags << "#{key}=#{value}"
+        end
+
+        # Secrets (Base64-encoded) (-e KEY_B64=encoded_value)
+        @secrets.each do |key, encoded_value|
+          flags << "-e"
+          flags << "#{key}_B64=#{encoded_value}"
+        end
+
+        # Docker run options (--cpus=2, --memory=4g, etc.)
+        flags.concat(@options)
+
+        # Remote user (--user USER)
+        if @user
+          flags << "--user"
+          flags << @user
+        end
+
+        # Workspace folder (-w /workspace)
+        if @workspace
+          flags << "-w"
+          flags << @workspace
+        end
+
+        flags
+      end
+
+      # Generate full Docker run command array
+      #
+      # @param name [String] Container name
+      # @return [Array<String>] Full docker run command with all flags
+      #
+      # @example
+      #   devcontainer.docker_run_command(name: "myapp-dev-1")
+      #   #=> ["docker", "run", "-d", "--name", "myapp-dev-1", "-p", "3000:3000", ..., "ruby:3.2"]
+      def docker_run_command(name:)
+        command = ["docker", "run"]
+
+        # Run in detached mode
+        command << "-d"
+
+        # Container name
+        command << "--name"
+        command << name
+
+        # Add all flags
+        command.concat(docker_run_flags)
+
+        # Image must be last
+        command << @image
+
+        command
+      end
+    end
+  end
+end

data/lib/kamal/dev/devcontainer_parser.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kamal
+  module Dev
+    # Parses VS Code devcontainer.json specifications into Docker configuration
+    #
+    # Handles JSON with comments (// and /* */), extracts container properties,
+    # and transforms them into a standardized configuration hash for Docker deployment.
+    #
+    # @example Basic usage
+    #   parser = DevcontainerParser.new(".devcontainer/devcontainer.json")
+    #   config = parser.parse
+    #   #=> {image: "ruby:3.2", ports: [3000], workspace: "/workspace", ...}
+    class DevcontainerParser
+      # Custom error for validation failures
+      class ValidationError < StandardError; end
+
+      attr_reader :file_path
+
+      # Initialize parser with devcontainer.json file path
+      #
+      # @param file_path [String] Path to devcontainer.json file
+      def initialize(file_path)
+        @file_path = file_path
+      end
+
+      # Parse devcontainer.json and return standardized config hash
+      #
+      # @return [Hash] Configuration hash with keys:
+      #   - :image [String] Docker image name
+      #   - :ports [Array<Integer>] Port mappings
+      #   - :mounts [Array<Hash>] Volume/bind mounts
+      #   - :env [Hash] Environment variables
+      #   - :options [Array<String>] Docker run options
+      #   - :user [String, nil] Remote user
+      #   - :workspace [String, nil] Workspace folder path
+      #
+      # @raise [Errno::ENOENT] if file doesn't exist
+      # @raise [JSON::ParserError] if JSON is malformed
+      # @raise [ValidationError] if required properties are missing
+      def parse
+        content = File.read(@file_path)
+        clean_content = strip_comments(content)
+        devcontainer_json = JSON.parse(clean_content)
+
+        validate_required_properties!(devcontainer_json)
+
+        {
+          image: extract_image(devcontainer_json),
+          ports: extract_ports(devcontainer_json),
+          mounts: extract_mounts(devcontainer_json),
+          env: extract_env(devcontainer_json),
+          options: extract_options(devcontainer_json),
+          user: extract_user(devcontainer_json),
+          workspace: extract_workspace(devcontainer_json)
+        }
+      end
+
+      # Check if devcontainer uses Docker Compose
+      #
+      # @return [Boolean] true if dockerComposeFile property is present
+      def uses_compose?
+        content = File.read(@file_path)
+        clean_content = strip_comments(content)
+        devcontainer_json = JSON.parse(clean_content)
+
+        devcontainer_json.key?("dockerComposeFile")
+      rescue
+        false
+      end
+
+      # Get path to compose file if present
+      #
+      # Returns path relative to .devcontainer/ directory
+      #
+      # @return [String, nil] Path to compose file or nil if not using compose
+      def compose_file_path
+        return nil unless uses_compose?
+
+        content = File.read(@file_path)
+        clean_content = strip_comments(content)
+        devcontainer_json = JSON.parse(clean_content)
+
+        compose_file = devcontainer_json["dockerComposeFile"]
+        return nil unless compose_file
+
+        # Handle array of compose files (use first one)
+        compose_file = compose_file.first if compose_file.is_a?(Array)
+
+        # Resolve path relative to .devcontainer directory
+        devcontainer_dir = File.dirname(@file_path)
+        File.join(devcontainer_dir, compose_file)
+      rescue
+        nil
+      end
+
+      private
+
+      # Strip single-line (//) and multi-line (/* */) comments from JSON
+      #
+      # @param content [String] Raw JSON content
+      # @return [String] JSON without comments
+      def strip_comments(content)
+        # Remove multi-line comments /* ... */
+        content = content.gsub(/\/\*.*?\*\//m, "")
+
+        # Remove single-line comments //  ...
+        # But preserve comments inside strings (basic approach)
+        content.gsub(/(?<!:)\/\/.*?$/, "")
+      end
+
+      # Validate that required properties exist
+      #
+      # @param json [Hash] Parsed JSON hash
+      # @raise [ValidationError] if image property is missing
+      def validate_required_properties!(json)
+        # Docker Compose files have their own validation - skip image check
+        return if json["dockerComposeFile"]
+
+        unless json["image"] || json["dockerfile"]
+          raise ValidationError, "Devcontainer.json must specify either 'image', 'dockerfile', or 'dockerComposeFile' property"
+        end
+      end
+
+      # Extract Docker image name
+      #
+      # @param json [Hash] Parsed devcontainer.json
+      # @return [String] Image name
+      # @raise [ValidationError] if neither image nor dockerfile specified
+      def extract_image(json)
+        if json["image"]
+          json["image"]
+        elsif json["dockerfile"]
+          # Dockerfile builds not yet supported - raise validation error
+          raise ValidationError, "Image property is required (Dockerfile builds not yet supported)"
+        else
+          raise ValidationError, "Image property is required"
+        end
+      end
+
+      # Extract forward ports
+      #
+      # @param json [Hash] Parsed devcontainer.json
+      # @return [Array<Integer>] List of ports to forward
+      def extract_ports(json)
+        return [] unless json["forwardPorts"]
+
+        Array(json["forwardPorts"]).map(&:to_i)
+      end
+
+      # Extract mounts (volumes and bind mounts)
+      #
+      # @param json [Hash] Parsed devcontainer.json
+      # @return [Array<Hash>] List of mount configurations with :source, :target, :type
+      def extract_mounts(json)
+        return [] unless json["mounts"]
+
+        Array(json["mounts"]).map do |mount|
+          {
+            source: mount["source"],
+            target: mount["target"],
+            type: mount["type"] || "bind"
+          }
+        end
+      end
+
+      # Extract container environment variables
+      #
+      # @param json [Hash] Parsed devcontainer.json
+      # @return [Hash] Environment variable key-value pairs
+      def extract_env(json)
+        json["containerEnv"] || {}
+      end
+
+      # Extract Docker run options (runArgs)
+      #
+      # @param json [Hash] Parsed devcontainer.json
+      # @return [Array<String>] Docker run arguments
+      def extract_options(json)
+        return [] unless json["runArgs"]
+
+        Array(json["runArgs"])
+      end
+
+      # Extract remote user
+      #
+      # @param json [Hash] Parsed devcontainer.json
+      # @return [String, nil] Remote user name
+      def extract_user(json)
+        json["remoteUser"]
+      end
+
+      # Extract workspace folder path
+      #
+      # @param json [Hash] Parsed devcontainer.json
+      # @return [String, nil] Workspace folder path
+      def extract_workspace(json)
+        json["workspaceFolder"]
+      end
+    end
+  end
+end