kamal-dev 0.3.0

data/lib/kamal/dev/registry.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Kamal
+  module Dev
+    # Registry configuration and authentication for image building and pushing
+    #
+    # Provides methods for:
+    # - Registry server configuration (default: ghcr.io)
+    # - Credential loading from environment variables
+    # - Image naming conventions ({registry}/{user}/{service}-dev:{tag})
+    # - Docker login command generation
+    #
+    # @example Basic usage
+    #   registry = Kamal::Dev::Registry.new(config)
+    #   image = registry.image_name("myapp")
+    #   # => "ghcr.io/ljuti/myapp-dev"
+    #
+    # @example With tag
+    #   registry.image_tag("myapp", "abc123")
+    #   # => "ghcr.io/ljuti/myapp-dev:abc123"
+    #
+    # @example Docker login
+    #   registry.login_command
+    #   # => ["docker", "login", "ghcr.io", "-u", "ljuti", "-p", "token"]
+    #
+    class Registry
+      attr_reader :config
+
+      # Initialize registry with configuration
+      #
+      # @param config [Kamal::Dev::Config] Configuration object
+      def initialize(config)
+        @config = config
+      end
+
+      # Registry server URL
+      #
+      # @return [String] Registry server (default: ghcr.io)
+      def server
+        config.registry_server
+      end
+
+      # Registry username loaded from environment variable
+      #
+      # @return [String, nil] Username from ENV
+      def username
+        config.registry_username
+      end
+
+      # Registry password/token loaded from environment variable
+      #
+      # @return [String, nil] Password from ENV
+      def password
+        config.registry_password
+      end
+
+      # Get full image name with registry server prepended if needed
+      #
+      # Supports both patterns:
+      # - Full path: "ghcr.io/org/app" → "ghcr.io/org/app"
+      # - Short path: "org/app" → "ghcr.io/org/app" (registry prepended)
+      # - Name only: "app" → "ghcr.io/app"
+      #
+      # @param image_ref [String] Image reference from config.image
+      # @return [String] Full image name with registry
+      def full_image_name(image_ref)
+        # Check if image already includes a registry
+        # Registry indicators: has a . (ghcr.io) or : (localhost:5000) in first component
+        first_component = image_ref.split("/").first
+
+        if first_component.include?(".") || first_component.include?(":")
+          # Already has registry: "ghcr.io/org/app", "docker.io/library/ruby", "localhost:5000/app"
+          image_ref
+        else
+          # No registry: "org/app" or "app" - prepend registry server
+          "#{server}/#{image_ref}"
+        end
+      end
+
+      # Generate image name without tag (DEPRECATED - kept for backward compatibility)
+      #
+      # @deprecated Use full_image_name(config.image) instead
+      # @param service [String] Service name (from config.service)
+      # @return [String] Full image name without tag
+      # @raise [Kamal::Dev::RegistryError] if username not configured
+      def image_name(service)
+        raise Kamal::Dev::RegistryError, "Registry username not configured" unless username
+
+        "#{server}/#{username}/#{service}-dev"
+      end
+
+      # Generate full image reference with tag
+      #
+      # @param image_base [String] Base image name (can be full or short path)
+      # @param tag [String] Image tag (timestamp, git SHA, or custom)
+      # @return [String] Full image reference with tag
+      def image_tag(image_base, tag)
+        base = (image_base.is_a?(String) && (image_base.include?("/") || image_base.include?("."))) ?
+                 full_image_name(image_base) :
+                 image_name(image_base)  # Backward compatibility
+        "#{base}:#{tag}"
+      end
+
+      # Generate docker login command
+      #
+      # @return [Array<String>] Docker login command array
+      # @raise [Kamal::Dev::RegistryError] if credentials not configured
+      # @example
+      #   registry.login_command
+      #   # => ["docker", "login", "ghcr.io", "-u", "ljuti", "-p", "token"]
+      def login_command
+        raise Kamal::Dev::RegistryError, "Registry credentials not configured" unless credentials_present?
+
+        ["docker", "login", server, "-u", username, "-p", password]
+      end
+
+      # Check if credentials are present
+      #
+      # @return [Boolean] true if username and password are set
+      def credentials_present?
+        !!(username && password)
+      end
+
+      # Generate timestamp-based tag
+      #
+      # Format: unix_timestamp (e.g., "1700000000")
+      #
+      # @return [String] Unix timestamp tag
+      def tag_with_timestamp
+        Time.now.to_i.to_s
+      end
+
+      # Generate git SHA-based tag
+      #
+      # Format: short_sha (e.g., "abc123f")
+      #
+      # @return [String, nil] Short git commit SHA or nil if git not available
+      def tag_with_git_sha
+        sha, _status = Open3.capture2("git", "rev-parse", "--short", "HEAD", err: :close)
+        sha = sha.strip
+        sha.empty? ? nil : sha
+      rescue
+        nil
+      end
+    end
+  end
+end

data/lib/kamal/dev/secrets_loader.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Kamal
+  module Dev
+    # Loads and processes secrets from .kamal/secrets file
+    #
+    # Parses shell script format (export KEY="value") and provides
+    # Base64-encoded values for container injection.
+    #
+    # @example Basic usage
+    #   loader = SecretsLoader.new(".kamal/secrets")
+    #   secrets = loader.load_secrets
+    #   #=> {"DATABASE_URL" => "base64_encoded_value", ...}
+    class SecretsLoader
+      # Custom error for missing secrets file
+      class SecretsNotFoundError < StandardError; end
+
+      # Custom error for secrets parsing failures
+      class SecretsParseError < StandardError; end
+
+      attr_reader :secrets_file
+
+      # Initialize secrets loader with file path
+      #
+      # @param secrets_file_path [String] Path to secrets file
+      def initialize(secrets_file_path = ".kamal/secrets")
+        @secrets_file = secrets_file_path
+      end
+
+      # Load and parse secrets from file
+      #
+      # @return [Hash<String, String>] Hash of secret keys to Base64-encoded values
+      # @raise [SecretsNotFoundError] if secrets file doesn't exist
+      # @raise [SecretsParseError] if file cannot be parsed
+      def load_secrets
+        unless File.exist?(@secrets_file)
+          raise SecretsNotFoundError, "Secrets file not found: #{@secrets_file}"
+        end
+
+        parse_secrets_file
+      end
+
+      # Load secrets for specific keys only
+      #
+      # @param keys [Array<String>] List of secret keys to load
+      # @return [Hash<String, String>] Hash of requested keys to Base64-encoded values
+      def load_secrets_for(keys)
+        all_secrets = load_secrets
+        keys.each_with_object({}) do |key, result|
+          result[key] = all_secrets[key] if all_secrets.key?(key)
+        end
+      end
+
+      private
+
+      # Parse shell script format secrets file
+      #
+      # Supports formats:
+      #   export KEY="value"
+      #   export KEY='value'
+      #   export KEY=value
+      #
+      # @return [Hash<String, String>] Parsed and Base64-encoded secrets
+      def parse_secrets_file
+        content = File.read(@secrets_file)
+        secrets = {}
+
+        content.each_line do |line|
+          # Skip comments and empty lines
+          next if line.strip.start_with?("#") || line.strip.empty?
+
+          # Match: export KEY="value" or export KEY='value' or export KEY=value
+          if line =~ /^\s*export\s+([A-Z_][A-Z0-9_]*)\s*=\s*(.+)$/
+            key = $1
+            value = $2.strip
+
+            # Remove quotes if present
+            value = value[1..-2] if value.start_with?('"', "'") && value.end_with?('"', "'")
+
+            # Base64 encode the value
+            secrets[key] = Base64.strict_encode64(value)
+          end
+        end
+
+        secrets
+      rescue => e
+        raise SecretsParseError, "Failed to parse secrets file: #{e.message}"
+      end
+    end
+  end
+end

data/lib/kamal/dev/state_manager.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "timeout"
+
+module Kamal
+  module Dev
+    # Manages deployment state file with file locking for concurrency safety
+    #
+    # Provides thread-safe read/write operations to `.kamal/dev_state.yml` using
+    # File.flock with exclusive locks for writes and shared locks for reads.
+    #
+    # State file format:
+    # ```yaml
+    # deployments:
+    #   container-name-1:
+    #     vm_id: "vm-123"
+    #     vm_ip: "1.2.3.4"
+    #     container_name: "container-name-1"
+    #     status: "running"
+    #     deployed_at: "2025-11-16T10:00:00Z"
+    # ```
+    #
+    # @example Basic usage
+    #   manager = StateManager.new(".kamal/dev_state.yml")
+    #   state = manager.read_state
+    #   manager.add_deployment({name: "myapp-dev-1", vm_id: "vm-123", ...})
+    class StateManager
+      # Lock timeout in seconds
+      LOCK_TIMEOUT = 10
+
+      attr_reader :state_file
+
+      # Custom error for lock timeouts
+      class LockTimeoutError < StandardError; end
+
+      # Initialize state manager with state file path
+      #
+      # @param state_file_path [String] Path to state YAML file
+      def initialize(state_file_path)
+        @state_file = state_file_path
+      end
+
+      # Read state with shared lock (multiple readers allowed)
+      #
+      # @return [Hash] State hash with deployment data
+      def read_state
+        with_lock(:shared) do |file|
+          content = file.read
+          return {} if content.empty?
+          YAML.safe_load(content, permitted_classes: [Symbol, Time], aliases: true, symbolize_names: false) || {}
+        end
+      rescue Errno::ENOENT
+        {} # File doesn't exist yet
+      end
+
+      # Write state with exclusive lock (single writer)
+      #
+      # @param state [Hash] State data to write
+      def write_state(state)
+        atomic_write(state)
+      end
+
+      # Update state (read-modify-write pattern with exclusive lock)
+      #
+      # @yield [state] Yields current state for modification
+      # @yieldparam state [Hash] Current state hash
+      # @yieldreturn [Hash] Modified state hash
+      def update_state
+        with_lock(:exclusive) do |file|
+          file.rewind
+          content = file.read
+          current_state = if content && !content.empty?
+            YAML.safe_load(content, permitted_classes: [Symbol, Time], aliases: true, symbolize_names: false) || {}
+          else
+            {}
+          end
+
+          new_state = yield(current_state)
+
+          atomic_write(new_state)
+        end
+      end
+
+      # Add a new deployment to state (single container)
+      #
+      # @param deployment [Hash] Deployment data with keys:
+      #   - :name [String] Container name (key in deployments hash)
+      #   - :vm_id [String] VM identifier
+      #   - :vm_ip [String] VM IP address
+      #   - :container_name [String] Docker container name
+      #   - :status [String] Deployment status
+      #   - :deployed_at [String] ISO 8601 timestamp
+      def add_deployment(deployment)
+        update_state do |state|
+          state["deployments"] ||= {}
+          state["deployments"][deployment[:name]] = {
+            "vm_id" => deployment[:vm_id],
+            "vm_ip" => deployment[:vm_ip],
+            "container_name" => deployment[:container_name],
+            "status" => deployment[:status],
+            "deployed_at" => deployment[:deployed_at]
+          }
+          state
+        end
+      end
+
+      # Add a compose stack deployment to state (multiple containers per VM)
+      #
+      # @param vm_name [String] VM identifier (e.g., "myapp-1")
+      # @param vm_id [String] Cloud provider VM ID
+      # @param vm_ip [String] VM IP address
+      # @param containers [Array<Hash>] Array of container hashes with keys:
+      #   - :name [String] Container name
+      #   - :service [String] Service name from compose file
+      #   - :image [String] Docker image reference
+      #   - :status [String] Container status
+      def add_compose_deployment(vm_name, vm_id, vm_ip, containers)
+        update_state do |state|
+          state["deployments"] ||= {}
+          state["deployments"][vm_name] = {
+            "vm_id" => vm_id,
+            "vm_ip" => vm_ip,
+            "deployed_at" => Time.now.utc.iso8601,
+            "type" => "compose",
+            "containers" => containers.map do |container|
+              {
+                "name" => container[:name],
+                "service" => container[:service],
+                "image" => container[:image],
+                "status" => container[:status]
+              }
+            end
+          }
+          state
+        end
+      end
+
+      # Update deployment status
+      #
+      # @param name [String] Container name
+      # @param new_status [String] New status value
+      def update_deployment_status(name, new_status)
+        update_state do |state|
+          if state.dig("deployments", name)
+            state["deployments"][name]["status"] = new_status
+          end
+          state
+        end
+      end
+
+      # Remove deployment from state
+      #
+      # @param name [String] Container name
+      def remove_deployment(name)
+        should_delete_file = false
+
+        update_state do |state|
+          state["deployments"]&.delete(name)
+
+          # Mark for deletion if no deployments remain
+          if state["deployments"].nil? || state["deployments"].empty?
+            should_delete_file = true
+          end
+
+          state
+        end
+
+        # Delete state file outside of lock
+        File.delete(@state_file) if should_delete_file && File.exist?(@state_file)
+      end
+
+      # List all deployments
+      #
+      # Returns deployments in a normalized format, handling both
+      # single container and compose (multi-container) deployments.
+      #
+      # @return [Hash] Hash of deployments keyed by container/VM name
+      def list_deployments
+        state = read_state
+        state["deployments"] || {}
+      end
+
+      # Check if deployment is a compose stack
+      #
+      # @param deployment_name [String] Deployment key name
+      # @return [Boolean] true if deployment is a compose stack
+      def compose_deployment?(deployment_name)
+        state = read_state
+        deployment = state.dig("deployments", deployment_name)
+        return false unless deployment
+
+        deployment["type"] == "compose" || deployment.key?("containers")
+      end
+
+      # Get containers for a deployment
+      #
+      # For single container deployments, returns array with one item.
+      # For compose deployments, returns all containers in the stack.
+      #
+      # @param deployment_name [String] Deployment key name
+      # @return [Array<Hash>] Array of container hashes
+      def get_containers(deployment_name)
+        state = read_state
+        deployment = state.dig("deployments", deployment_name)
+        return [] unless deployment
+
+        if deployment.key?("containers")
+          # Compose deployment - return container array
+          deployment["containers"]
+        else
+          # Single container deployment - wrap in array
+          [{
+            "name" => deployment["container_name"],
+            "service" => "app",
+            "image" => "unknown",
+            "status" => deployment["status"]
+          }]
+        end
+      end
+
+      private
+
+      # Acquire lock and execute block
+      #
+      # @param mode [Symbol] :shared or :exclusive
+      # @yield [file] File handle with lock acquired
+      def with_lock(mode)
+        lock_mode = (mode == :exclusive) ? File::LOCK_EX : File::LOCK_SH
+
+        FileUtils.mkdir_p(File.dirname(@state_file))
+
+        File.open(@state_file, File::RDWR | File::CREAT, 0o644) do |file|
+          acquire_lock(file, lock_mode)
+          yield(file)
+        end
+      end
+
+      # Acquire file lock with timeout
+      #
+      # @param file [File] File handle
+      # @param lock_mode [Integer] File::LOCK_SH or File::LOCK_EX
+      # @raise [LockTimeoutError] if lock cannot be acquired within timeout
+      def acquire_lock(file, lock_mode)
+        Timeout.timeout(LOCK_TIMEOUT) do
+          file.flock(lock_mode)
+        end
+      rescue Timeout::Error
+        mode_name = (lock_mode == File::LOCK_EX) ? "exclusive" : "shared"
+        raise LockTimeoutError, "Could not acquire #{mode_name} lock on state file after #{LOCK_TIMEOUT}s"
+      end
+
+      # Atomic write using temp file + rename
+      #
+      # @param state [Hash] State data to write
+      def atomic_write(state)
+        FileUtils.mkdir_p(File.dirname(@state_file))
+
+        tmp_file = "#{@state_file}.tmp.#{Process.pid}"
+
+        begin
+          File.write(tmp_file, YAML.dump(state))
+          File.rename(tmp_file, @state_file) # Atomic on POSIX
+        ensure
+          File.delete(tmp_file) if File.exist?(tmp_file)
+        end
+      end
+    end
+  end
+end

data/lib/kamal/dev/templates/dev-entrypoint.sh

@@ -0,0 +1,44 @@
+#!/bin/sh
+# Kamal Dev entrypoint script
+# Handles git cloning for remote deployments while preserving local devcontainer workflow
+
+set -e
+
+# Check if this is a kamal-dev remote deployment (env vars will be set)
+if [ -n "$KAMAL_DEV_GIT_REPO" ]; then
+  echo "[kamal-dev] Remote deployment detected"
+
+  # Clone repository if not already present
+  if [ ! -d "$KAMAL_DEV_WORKSPACE_FOLDER/.git" ]; then
+    echo "[kamal-dev] Cloning $KAMAL_DEV_GIT_REPO (branch: $KAMAL_DEV_GIT_BRANCH)"
+    mkdir -p "$KAMAL_DEV_WORKSPACE_FOLDER"
+
+    # Use token authentication if provided (for private repositories)
+    if [ -n "$KAMAL_DEV_GIT_TOKEN" ]; then
+      # Extract repo URL components for token injection
+      # Supports: https://github.com/user/repo.git
+      REPO_URL_WITH_TOKEN=$(echo "$KAMAL_DEV_GIT_REPO" | sed "s|https://|https://${KAMAL_DEV_GIT_TOKEN}@|")
+      git clone --depth 1 --branch "$KAMAL_DEV_GIT_BRANCH" "$REPO_URL_WITH_TOKEN" "$KAMAL_DEV_WORKSPACE_FOLDER"
+
+      # Configure git to cache credentials for future operations (pull/push)
+      cd "$KAMAL_DEV_WORKSPACE_FOLDER"
+      git config credential.helper store
+      echo "https://${KAMAL_DEV_GIT_TOKEN}@github.com" > ~/.git-credentials
+      chmod 600 ~/.git-credentials
+    else
+      # Public repository or SSH (if configured separately)
+      git clone --depth 1 --branch "$KAMAL_DEV_GIT_BRANCH" "$KAMAL_DEV_GIT_REPO" "$KAMAL_DEV_WORKSPACE_FOLDER"
+    fi
+
+    echo "[kamal-dev] Clone complete: $KAMAL_DEV_WORKSPACE_FOLDER"
+  else
+    echo "[kamal-dev] Repository already cloned at $KAMAL_DEV_WORKSPACE_FOLDER"
+    # Optionally pull latest changes
+    # cd "$KAMAL_DEV_WORKSPACE_FOLDER" && git pull
+  fi
+else
+  echo "[kamal-dev] Local development mode (using mounted code)"
+fi
+
+# Execute the original command (CMD from Dockerfile or docker-compose)
+exec "$@"

data/lib/kamal/dev/templates/dev.yml

@@ -0,0 +1,93 @@
+# Kamal Dev Configuration
+# Deploy and manage development container workspaces to cloud infrastructure
+
+# Service name (used as prefix for container naming)
+service: myapp-dev
+
+# Destination image (where to push/deploy) - matches Kamal's usage
+# Registry server will be prepended if not included
+# Examples:
+#   myorg/myapp          → ghcr.io/myorg/myapp (registry prepended)
+#   ghcr.io/myorg/myapp  → ghcr.io/myorg/myapp (explicit registry)
+image: myorg/myapp
+
+# Build configuration (optional - omit to deploy existing image)
+# Option 1: Build from devcontainer.json
+build:
+  devcontainer: .devcontainer/devcontainer.json
+
+# Option 2: Build from Dockerfile
+# build:
+#   dockerfile: .devcontainer/Dockerfile
+#   context: .devcontainer
+
+# Option 3: Deploy existing image (no build needed)
+# Remove the build: section entirely and set image to existing image:
+# image: ruby:3.2
+
+# Container registry configuration (for building and pushing custom images)
+# Required when using build: section
+registry:
+  server: ghcr.io                # Registry server (default: ghcr.io - GitHub Container Registry)
+                                  # Alternatives: docker.io, your-custom-registry.io
+  username: GITHUB_USER           # Environment variable name for registry username
+  password: GITHUB_TOKEN          # Environment variable name for registry password/token
+                                  # For GHCR: create a Personal Access Token with write:packages scope
+
+# Cloud provider configuration
+provider:
+  type: upcloud              # Cloud provider (currently: upcloud)
+  zone: us-nyc1              # Data center location (upcloud zones: us-nyc1, de-fra1, uk-lon1, etc.)
+  plan: 1xCPU-2GB            # VM plan/size (upcloud plans: 1xCPU-1GB, 1xCPU-2GB, 2xCPU-4GB, etc.)
+  # storage_template: "01000000-0000-4000-8000-000030220200"  # OS template UUID (optional - defaults to Ubuntu 24.04 LTS)
+                                                                     # Ubuntu 24.04 LTS: 01000000-0000-4000-8000-000030240200 (default)
+                                                                     # Ubuntu 22.04 LTS: 01000000-0000-4000-8000-000030220200
+                                                                     # Find UUIDs in UpCloud control panel under Templates
+
+# Secrets to inject from .kamal/secrets file
+# These will be loaded and injected as Base64-encoded environment variables
+secrets:
+  - UPCLOUD_USERNAME         # Required: UpCloud API username
+  - UPCLOUD_PASSWORD         # Required: UpCloud API password
+  # Registry credentials (required if using registry.username/password above):
+  # - GITHUB_USER            # For GitHub Container Registry (ghcr.io)
+  # - GITHUB_TOKEN           # Personal Access Token with write:packages scope
+  # - DOCKER_HUB_USERNAME    # For Docker Hub (hub.docker.com)
+  # - DOCKER_HUB_TOKEN       # Docker Hub access token
+  # Add your application secrets here:
+  # - DATABASE_URL
+  # - API_KEY
+
+# Path to secrets file (default: .kamal/secrets)
+# secrets_file: .kamal/secrets
+
+# SSH configuration
+ssh:
+  key_path: ~/.ssh/id_rsa.pub  # SSH public key for VM access (default: ~/.ssh/id_rsa.pub)
+
+# Git clone configuration (for DevPod-style remote development)
+# When configured, code is cloned from repository on deployment
+# Local devcontainer usage (VS Code) is unaffected - uses mounted code
+git:
+  repository: https://github.com/yourorg/yourrepo.git  # Git repository URL (HTTPS format)
+  branch: main                                         # Branch to checkout (default: main)
+  workspace_folder: /workspaces/myapp                  # Where to clone code (should match devcontainer workspaceFolder)
+  token: GITHUB_TOKEN                                  # Environment variable name containing Personal Access Token (for private repos)
+                                                       # Generate token at: https://github.com/settings/tokens
+                                                       # Scopes needed: repo (for private repos)
+                                                       # Add to .kamal/secrets: export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
+
+# Default resource limits for containers
+defaults:
+  cpus: 2                    # CPU limit (cores)
+  memory: 4g                 # Memory limit
+  memory_swap: 8g            # Swap limit (optional)
+
+# VM and container deployment configuration
+vms:
+  count: 3                   # Number of workspaces to deploy
+  spread: false              # false = colocate containers, true = one container per VM
+
+# Container naming pattern
+naming:
+  pattern: "{service}-{index}"  # Results in: myapp-dev-1, myapp-dev-2, etc.

data/lib/kamal/dev/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Dev
+    VERSION = "0.3.0"
+  end
+end

data/lib/kamal/dev.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Load base Kamal first to ensure CLI classes are available
+require "kamal"
+
+require_relative "dev/version"
+require_relative "dev/config"
+require_relative "dev/devcontainer_parser"
+require_relative "dev/devcontainer"
+require_relative "dev/state_manager"
+require_relative "dev/secrets_loader"
+require_relative "dev/registry"
+require_relative "dev/builder"
+require_relative "providers/base"
+require_relative "providers/upcloud"
+require_relative "cli/dev"
+
+module Kamal
+  module Dev
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+    class RegistryError < Error; end
+    class BuildError < Error; end
+    class DeploymentError < Error; end
+  end
+end
+
+# Hook into Kamal's CLI to register the 'dev' subcommand
+# This allows users to run: kamal dev deploy, kamal dev list, etc.
+Kamal::Cli::Main.class_eval do
+  desc "dev", "Manage development containers"
+  subcommand "dev", Kamal::Cli::Dev
+end