superkick 0.1.0

data/lib/superkick/integrations/docker/client.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "socket"
+require "uri"
+
+module Superkick
+  module Integrations
+    module Docker
+      # Thin Faraday-based wrapper around the Docker Engine API.
+      #
+      # Supports Unix socket and TCP+TLS connections. Accepts `connection:`
+      # for test injection (Faraday test adapter).
+      #
+      # Only covers the endpoints needed by the Docker runtime:
+      # containers (create/start/stop/remove/inspect) and images (pull/exists).
+      class Client
+        API_VERSION = "v1.47"
+        TIMEOUT = 30 # seconds
+
+        class Error < StandardError
+          attr_reader :status, :body
+
+          def initialize(message, status: nil, body: nil)
+            @status = status
+            @body = body
+            super(message)
+          end
+        end
+
+        class NotFoundError < Error; end
+        class ConflictError < Error; end
+        class ConnectionError < Error; end
+
+        # @param host       [String] Docker daemon address (unix:// or tcp://)
+        # @param tls        [Hash, nil] TLS config { ca:, cert:, key: } for TCP
+        # @param connection [Faraday::Connection, nil] pre-built connection (for testing)
+        def initialize(host: "unix:///var/run/docker.sock", tls: nil, connection: nil)
+          @host = host
+          @tls = tls || {}
+          @connection = connection || build_connection
+        end
+
+        # POST /containers/create?name=<name>
+        #
+        # @param name   [String] container name
+        # @param config [Hash]   Docker container config (Image, Cmd, Env, etc.)
+        # @return [Hash] { id: String, warnings: Array }
+        def create_container(name:, config:)
+          response = request(:post, "/containers/create", params: {name:}, body: config)
+          {id: response[:Id], warnings: response[:Warnings] || []}
+        end
+
+        # POST /containers/<id>/start
+        def start_container(container_id:)
+          request(:post, "/containers/#{container_id}/start")
+          nil
+        end
+
+        # POST /containers/<id>/stop?t=<timeout>
+        def stop_container(container_id:, timeout: 30)
+          request(:post, "/containers/#{container_id}/stop", params: {t: timeout})
+          nil
+        rescue NotFoundError
+          nil # already gone
+        end
+
+        # DELETE /containers/<id>?force=<force>
+        def remove_container(container_id:, force: false)
+          request(:delete, "/containers/#{container_id}", params: {force:})
+          nil
+        rescue NotFoundError
+          nil # already gone
+        end
+
+        # GET /containers/<id>/json
+        #
+        # @return [Hash] full container inspect response (string keys from Docker API)
+        def inspect_container(container_id:)
+          request(:get, "/containers/#{container_id}/json", symbolize: false)
+        end
+
+        # POST /images/create?fromImage=<image>&tag=<tag>
+        #
+        # Blocks until the pull completes. Docker streams progress as JSON lines;
+        # we consume them all and discard.
+        def pull_image(image:, registry_auth: nil)
+          image_ref, tag = parse_image_ref(image)
+          headers = {}
+          headers["X-Registry-Auth"] = registry_auth if registry_auth
+
+          # The pull endpoint streams JSON progress — we just consume the full response.
+          request(:post, "/images/create",
+            params: {fromImage: image_ref, tag:},
+            headers:,
+            symbolize: false)
+          nil
+        end
+
+        # GET /images/<image>/json
+        #
+        # @return [Boolean] true if image exists locally
+        def image_exists?(image:)
+          request(:get, "/images/#{ERB::Util.url_encode(image)}/json", symbolize: false)
+          true
+        rescue NotFoundError
+          false
+        end
+
+        # GET /_ping
+        #
+        # @return [Boolean] true if Docker daemon is reachable
+        def ping
+          @connection.get("/#{API_VERSION}/_ping")
+          true
+        rescue Faraday::Error
+          false
+        end
+
+        private
+
+        def request(method, path, params: nil, body: nil, headers: nil, symbolize: true)
+          url = "/#{API_VERSION}#{path}"
+
+          response = @connection.run_request(method, url, body&.to_json, headers) do |req|
+            req.params.update(params) if params
+            req.headers["Content-Type"] = "application/json" if body
+          end
+
+          handle_response(response, symbolize:)
+        rescue Faraday::ConnectionFailed => e
+          raise ConnectionError.new("Docker connection failed: #{e.message}")
+        rescue Faraday::TimeoutError => e
+          raise ConnectionError.new("Docker request timed out: #{e.message}")
+        end
+
+        def handle_response(response, symbolize: true)
+          case response.status
+          when 200, 201, 204
+            return nil if response.body.nil? || response.body.empty?
+            JSON.parse(response.body, symbolize_names: symbolize)
+          when 304
+            nil
+          when 404
+            raise NotFoundError.new(error_message(response), status: 404, body: response.body)
+          when 409
+            raise ConflictError.new(error_message(response), status: 409, body: response.body)
+          else
+            raise Error.new(error_message(response), status: response.status, body: response.body)
+          end
+        end
+
+        def error_message(response)
+          parsed = JSON.parse(response.body, symbolize_names: true)
+          parsed[:message] || "Docker API error (HTTP #{response.status})"
+        rescue JSON::ParserError
+          "Docker API error (HTTP #{response.status})"
+        end
+
+        def parse_image_ref(image)
+          # Split "image:tag" into ["image", "tag"], defaulting tag to "latest"
+          parts = image.split(":", 2)
+          if parts.length == 2 && !parts[1].include?("/")
+            [parts[0], parts[1]]
+          else
+            [image, "latest"]
+          end
+        end
+
+        def build_connection
+          if @host.start_with?("unix://")
+            build_unix_connection
+          else
+            build_tcp_connection
+          end
+        end
+
+        def build_unix_connection
+          socket_path = @host.delete_prefix("unix://")
+
+          Faraday.new(url: "http://localhost") do |f|
+            f.options.timeout = TIMEOUT
+            f.options.open_timeout = TIMEOUT
+            f.adapter :test # placeholder — replaced below
+          end.tap do |conn|
+            # Replace the adapter with our Unix socket adapter
+            conn.builder.delete(Faraday::Adapter::Test)
+            conn.builder.adapter(UnixSocketAdapter, socket_path:)
+          end
+        end
+
+        def build_tcp_connection
+          url = @host.sub(/\Atcp:\/\//, "https://")
+          ssl_options = {}
+
+          if @tls[:ca]
+            ssl_options[:ca_file] = @tls[:ca]
+            ssl_options[:client_cert] = OpenSSL::X509::Certificate.new(File.read(@tls[:cert])) if @tls[:cert]
+            ssl_options[:client_key] = OpenSSL::PKey.read(File.read(@tls[:key])) if @tls[:key]
+          end
+
+          Faraday.new(url:, ssl: ssl_options) do |f|
+            f.options.timeout = TIMEOUT
+            f.options.open_timeout = TIMEOUT
+          end
+        end
+
+        # Minimal Faraday adapter that sends HTTP requests over a Unix socket.
+        # Only handles the simple synchronous request/response pattern used by
+        # the Docker Engine API.
+        class UnixSocketAdapter < Faraday::Adapter
+          def initialize(app, socket_path:)
+            super(app)
+            @socket_path = socket_path
+          end
+
+          def call(env)
+            super
+
+            sock = UNIXSocket.new(@socket_path)
+            begin
+              write_request(sock, env)
+              status, headers, body = read_response(sock)
+
+              save_response(env, status, body, headers)
+            ensure
+              sock.close
+            end
+          end
+
+          private
+
+          def write_request(sock, env)
+            path = env.url.request_uri
+            method = env.method.to_s.upcase
+
+            sock.write("#{method} #{path} HTTP/1.1\r\n")
+            sock.write("Host: localhost\r\n")
+
+            env.request_headers.each do |key, value|
+              sock.write("#{key}: #{value}\r\n")
+            end
+
+            if env.body
+              sock.write("Content-Length: #{env.body.bytesize}\r\n")
+            end
+
+            sock.write("\r\n")
+            sock.write(env.body) if env.body
+          end
+
+          def read_response(sock)
+            status_line = sock.gets
+            status = status_line.split(" ", 3)[1].to_i
+
+            headers = {}
+            while (line = sock.gets) && line != "\r\n"
+              key, value = line.split(":", 2)
+              headers[key.strip.downcase] = value.strip
+            end
+
+            body = read_body(sock, headers)
+            [status, headers, body]
+          end
+
+          def read_body(sock, headers)
+            if headers["transfer-encoding"]&.include?("chunked")
+              read_chunked_body(sock)
+            elsif headers["content-length"]
+              sock.read(headers["content-length"].to_i)
+            else
+              sock.read
+            end
+          end
+
+          def read_chunked_body(sock)
+            body = +""
+            loop do
+              size_line = sock.gets
+              break unless size_line
+
+              size = size_line.strip.to_i(16)
+              break if size == 0
+
+              body << sock.read(size)
+              sock.gets # consume trailing \r\n
+            end
+            body
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/docker/runtime.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+module Superkick
+  module Integrations
+    module Docker
+      # Docker runtime — provisions spawned agents in Docker containers via the
+      # Docker Engine API. Supports both local mode (Unix socket mount) and hosted
+      # mode (HTTPS + WebSocket) for server connectivity.
+      #
+      # When the +server+ context indicates local transport, the runtime
+      # auto-injects a bind mount for the Superkick run directory and sets
+      # SUPERKICK_DIR in the container so agents can communicate with the
+      # local server without manual volume configuration.
+      class Runtime < Superkick::Agent::Runtime
+        Handle = Data.define(:container_id, :container_name)
+
+        MEMORY_UNITS = {"K" => 1024, "M" => 1024**2, "G" => 1024**3, "T" => 1024**4}.freeze
+        NANO_CPUS_PER_CPU = 1_000_000_000
+        CONTAINER_SUPERKICK_DIR = "/superkick"
+
+        def self.type = :docker
+
+        # @param image             [String]      Docker image (required)
+        # @param host              [String]      Docker daemon address (default: Unix socket)
+        # @param tls               [Hash, nil]   TLS config { ca:, cert:, key: } for TCP
+        # @param pull_policy       [Symbol]      :always, :missing, :never (default: :missing)
+        # @param registry          [Hash, nil]   { username:, password:, server: } for private registries
+        # @param memory            [String, Integer, nil] memory limit (e.g. "4G", 4294967296)
+        # @param cpu               [Numeric, nil] CPU cores (e.g. 2 → 2_000_000_000 NanoCPUs)
+        # @param network           [String, nil] Docker network name
+        # @param stop_timeout      [Integer]     seconds before SIGKILL after SIGTERM (default: 30)
+        # @param auto_remove       [Boolean]     remove container after exit (default: true)
+        # @param env               [Hash, nil]   additional environment variables
+        # @param volumes           [Array, nil]  volume mount strings (e.g. ["/host:/container:ro"])
+        # @param labels            [Hash, nil]   container labels
+        # @param privileged        [Boolean]     run container in privileged mode (default: false)
+        # @param cap_add           [Array, nil]  Linux capabilities to add (e.g. ["SYS_ADMIN"])
+        # @param security_opt      [Array, nil]  security options (e.g. ["seccomp:unconfined"])
+        # @param container_runtime [String, nil] OCI runtime (e.g. "sysbox-runc")
+        # @param server            [Hash]        Server context from Configuration ({ type:, base_dir: })
+        # @param connection        [Faraday::Connection, nil] pre-built connection for testing
+        def initialize(image:, host: "unix:///var/run/docker.sock", tls: nil,
+          pull_policy: :missing, registry: nil, memory: nil, cpu: nil,
+          network: nil, stop_timeout: 30, auto_remove: true, env: nil,
+          volumes: nil, labels: nil, privileged: false, cap_add: nil,
+          security_opt: nil, container_runtime: nil, server: {},
+          connection: nil)
+          @image = image
+          @pull_policy = pull_policy.to_sym
+          @registry = registry
+          @memory = memory
+          @cpu = cpu
+          @network = network
+          @stop_timeout = stop_timeout
+          @auto_remove = auto_remove
+          @env = env || {}
+          @volumes = volumes || []
+          @labels = labels || {}
+          @privileged = privileged
+          @cap_add = cap_add || []
+          @security_opt = security_opt || []
+          @container_runtime = container_runtime
+          @client = Client.new(host:, tls:, connection:)
+
+          apply_local_connectivity(server[:base_dir]) if server[:type] == :local
+        end
+
+        # Provision a Docker container for the agent.
+        #
+        # @param agent_id [String]
+        # @param config   [Hash] { env: Hash, command: Array, working_dir: String }
+        # @return [Handle]
+        def provision(agent_id:, config:)
+          ensure_image_available
+
+          container_name = "superkick-#{agent_id}"
+          container_config = build_container_config(agent_id:, config:)
+
+          result = @client.create_container(name: container_name, config: container_config)
+          container_id = result[:id]
+
+          begin
+            @client.start_container(container_id:)
+          rescue Client::Error => e
+            # Clean up the created container if start fails
+            @client.remove_container(container_id:, force: true)
+            raise e
+          end
+
+          Superkick.logger.info("runtime:docker") do
+            "Started container #{container_id[0..11]} (#{container_name}) for #{agent_id}"
+          end
+
+          Handle.new(container_id:, container_name:)
+        end
+
+        # Stop and optionally remove the container.
+        #
+        # @param handle [Handle]
+        def terminate(handle:)
+          @client.stop_container(container_id: handle.container_id, timeout: @stop_timeout)
+          @client.remove_container(container_id: handle.container_id, force: true) unless @auto_remove
+        rescue Client::NotFoundError
+          nil # container already gone
+        rescue Client::Error => e
+          Superkick.logger.warn("runtime:docker") { "Terminate error for #{handle.container_id}: #{e.message}" }
+        end
+
+        # Check if the container is still running.
+        #
+        # @param handle [Handle]
+        # @return [Boolean]
+        def alive?(handle:)
+          info = @client.inspect_container(container_id: handle.container_id)
+          info.dig("State", "Running") == true
+        rescue Client::Error
+          false
+        end
+
+        # @param handle [Handle]
+        # @return [Hash]
+        def metadata(handle:)
+          {container_id: handle.container_id, container_name: handle.container_name}
+        end
+
+        private
+
+        def ensure_image_available
+          case @pull_policy
+          when :always
+            pull_image
+          when :missing
+            pull_image unless @client.image_exists?(image: @image)
+          when :never
+            nil
+          end
+        end
+
+        def pull_image
+          auth = build_registry_auth
+          Superkick.logger.info("runtime:docker") { "Pulling image #{@image}" }
+          @client.pull_image(image: @image, registry_auth: auth)
+        end
+
+        def build_registry_auth
+          return nil unless @registry&.any?
+
+          Base64.urlsafe_encode64({
+            username: @registry[:username],
+            password: @registry[:password],
+            serveraddress: @registry[:server]
+          }.compact.to_json)
+        end
+
+        def build_container_config(agent_id:, config:)
+          merged_env = @env.merge(config[:env] || {})
+          env_array = merged_env.map { |k, v| "#{k}=#{v}" }
+
+          {
+            Image: @image,
+            Cmd: config[:command],
+            Env: env_array,
+            WorkingDir: config[:working_dir],
+            Labels: @labels.merge("superkick.agent_id" => agent_id),
+            StopTimeout: @stop_timeout,
+            HostConfig: build_host_config
+          }
+        end
+
+        def build_host_config
+          host_config = {}
+          host_config[:Memory] = parse_memory(@memory) if @memory
+          host_config[:NanoCpus] = (@cpu * NANO_CPUS_PER_CPU).to_i if @cpu
+          host_config[:NetworkMode] = @network if @network
+          host_config[:Binds] = @volumes if @volumes.any?
+          host_config[:AutoRemove] = @auto_remove
+          host_config[:Privileged] = true if @privileged
+          host_config[:CapAdd] = @cap_add if @cap_add.any?
+          host_config[:SecurityOpt] = @security_opt if @security_opt.any?
+          host_config[:Runtime] = @container_runtime if @container_runtime
+          host_config
+        end
+
+        # Auto-inject run directory mount and SUPERKICK_DIR env var for local
+        # server connectivity. The env var is set as a default — user-configured
+        # env values take precedence.
+        def apply_local_connectivity(base_dir)
+          run_dir = File.join(base_dir, "run")
+          container_run_dir = File.join(CONTAINER_SUPERKICK_DIR, "run")
+
+          @volumes += ["#{run_dir}:#{container_run_dir}"]
+          @env = {"SUPERKICK_DIR" => CONTAINER_SUPERKICK_DIR}.merge(@env)
+        end
+
+        def parse_memory(value)
+          return value if value.is_a?(Integer)
+
+          match = value.to_s.match(/\A(\d+(?:\.\d+)?)\s*([KMGT])?B?\z/i)
+          raise ArgumentError, "Invalid memory value: #{value.inspect}" unless match
+
+          number = match[1].to_f
+          unit = match[2]&.upcase
+
+          if unit && MEMORY_UNITS[unit]
+            (number * MEMORY_UNITS[unit]).to_i
+          else
+            number.to_i
+          end
+        end
+      end
+    end
+  end
+end
+
+Superkick::Agent::Runtime.register(Superkick::Integrations::Docker::Runtime)

data/lib/superkick/integrations/docker.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "docker/client"
+require_relative "docker/runtime"

data/lib/superkick/integrations/git/repository_source.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Integrations
+    module Git
+      # Git::RepositorySource — single-repository source for URL-based git repos.
+      #
+      # Use when the repository is remote (no local path). The URL is stored on
+      # the Repository and used by the Git VersionControl adapter at acquire time.
+      #
+      # Config:
+      #   type: git
+      #   url: git@github.com:company/api.git   # required
+      #
+      # YAML usage:
+      #   repositories:
+      #     api:
+      #       type: git
+      #       url: git@github.com:company/api.git
+      class RepositorySource < Superkick::RepositorySource
+        def self.type = :git
+
+        def self.setup_label = "Git URL"
+
+        def self.setup_config
+          <<~YAML
+            upstream:
+              type: git
+              url: https://github.com/org/repo.git
+          YAML
+        end
+
+        def initialize(config = {})
+          @url = config[:url]
+          raise ArgumentError, "Git repository source requires url:" unless @url
+
+          name = config[:name]&.to_sym || infer_name(@url)
+
+          @repositories = {
+            name => Repository.new(
+              name:,
+              url: @url,
+              version_control: :git
+            )
+          }.freeze
+        end
+
+        attr_reader :repositories
+
+        private
+
+        def infer_name(url)
+          # Extract repo name from URL:
+          #   git@github.com:org/repo.git → repo
+          #   https://github.com/org/repo.git → repo
+          #   https://github.com/org/repo → repo
+          basename = url.split("/").last || url.split(":").last
+          basename = basename.sub(/\.git\z/, "")
+          basename.to_sym
+        end
+      end
+    end
+  end
+
+  RepositorySource.register(Integrations::Git::RepositorySource)
+end

data/lib/superkick/integrations/git/version_control.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Integrations
+    module Git
+      # Git version control adapter.
+      #
+      # Acquires an isolated working copy using the best available strategy:
+      #   - When the source has a local path → use git worktree (fast, shared objects)
+      #   - When only a URL is available → git clone + create branch
+      #
+      # Teardown reverses whichever strategy was used.
+      class VersionControl < Superkick::VersionControl
+        def self.type = :git
+
+        # Probe — detects git repositories by the presence of .git.
+        # .git can be a directory (normal repo) or a file (worktree).
+        class Probe < Superkick::VersionControl::Probe
+          def self.type = :git
+
+          def self.detect_at(path:)
+            return {type: :git} if File.exist?(File.join(path, ".git"))
+            nil
+          end
+        end
+
+        # Acquire an isolated working copy.
+        #
+        # @param source [Repository] the repository (must have path or url)
+        # @param destination [String] absolute path for the working copy
+        # @param branch [String] branch name to create
+        # @param base_branch [String] branch to base from (default: "main")
+        def acquire(source:, destination:, branch:, base_branch: "main")
+          if source.path && File.directory?(source.path)
+            acquire_via_worktree(source_path: source.path, destination:, branch:, base_branch:)
+          elsif source.url
+            acquire_via_clone(url: source.url, destination:, branch:, base_branch:)
+          else
+            raise Poller::FatalError,
+              "Repository #{source.name} has neither a local path nor a URL — cannot acquire"
+          end
+        end
+
+        # Remove the isolated working copy.
+        #
+        # @param destination [String] absolute path of the working copy
+        def teardown(destination:)
+          return unless destination && File.directory?(destination)
+
+          git_file = File.join(destination, ".git")
+
+          if File.file?(git_file) && File.read(git_file).start_with?("gitdir:")
+            teardown_worktree(destination:, git_file:)
+          else
+            teardown_clone(destination:)
+          end
+        rescue => e
+          Superkick.logger.warn("version_control:git") { "Teardown failed: #{e.message}" }
+        end
+
+        private
+
+        # ── Worktree strategy ────────────────────────────────────────────────
+
+        def acquire_via_worktree(source_path:, destination:, branch:, base_branch:)
+          return if File.directory?(destination)
+
+          FileUtils.mkdir_p(File.dirname(destination))
+
+          ProcessRunner.run(
+            "git worktree add -b #{shell_escape(branch)} #{shell_escape(destination)} #{shell_escape(base_branch)}",
+            timeout: 60, chdir: source_path
+          )
+        end
+
+        def teardown_worktree(destination:, git_file:)
+          content = File.read(git_file)
+          gitdir = content.sub("gitdir:", "").strip
+          repository_root = File.expand_path(File.join(gitdir, "..", "..", ".."))
+
+          return unless File.directory?(File.join(repository_root, ".git"))
+
+          ProcessRunner.run(
+            "git worktree remove #{shell_escape(destination)} --force",
+            timeout: 30, chdir: repository_root
+          )
+        end
+
+        # ── Clone strategy ──────────────────────────────────────────────────
+
+        def acquire_via_clone(url:, destination:, branch:, base_branch:)
+          return if File.directory?(destination)
+
+          FileUtils.mkdir_p(File.dirname(destination))
+
+          ProcessRunner.run(
+            "git clone --branch #{shell_escape(base_branch)} #{shell_escape(url)} #{shell_escape(destination)}",
+            timeout: 300
+          )
+
+          ProcessRunner.run(
+            "git checkout -b #{shell_escape(branch)}",
+            timeout: 30, chdir: destination
+          )
+        end
+
+        def teardown_clone(destination:)
+          FileUtils.rm_rf(destination)
+        end
+
+        # ── Helpers ─────────────────────────────────────────────────────────
+
+        def shell_escape(str)
+          Shellwords.escape(str.to_s)
+        end
+      end
+    end
+  end
+end