kitsune-kit 0.4.1 → 0.6.0

data/lib/kitsune/kit/workflows/build_plan.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../plan"
+require_relative "../result"
+require_relative "base"
+
+module Kitsune
+  module Kit
+    module Workflows
+      class BuildPlan < Base
+        def initialize(config:, operations:, event_bus: Events::NullBus.new, clock: Clock.new)
+          super(config: config, event_bus: event_bus, clock: clock)
+          @operations = operations
+        end
+
+        def call
+          started_at = monotonic_time
+          emit("run_started", command: "plan", environment: config.environment)
+          changes = @operations.map(&:plan)
+          plan = Plan.new(environment: config.environment, changes: changes)
+          emit(
+            "plan_built",
+            changed_count: plan.changed_count,
+            unchanged_count: plan.changes.length - plan.changed_count,
+            destructive: plan.destructive?
+          )
+          emit("run_finished", status: "success", duration_ms: elapsed_ms(started_at))
+          Result.success(plan, metadata: { run_id: run_id })
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/workflows/destroy_server.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../result"
+require_relative "base"
+
+module Kitsune
+  module Kit
+    module Workflows
+      class DestroyServer < Base
+        def initialize(config:, provider:, state_store:, dns_operation: nil, event_bus: Events::NullBus.new,
+                       clock: Clock.new)
+          super(config: config, event_bus: event_bus, clock: clock)
+          @provider = provider
+          @state_store = state_store
+          @dns_operation = dns_operation
+        end
+
+        def call(confirmation:)
+          @state_store.with_execution_lock(config.environment) { call_unlocked(confirmation: confirmation) }
+        end
+
+        private
+
+        def call_unlocked(confirmation:)
+          state = @state_store.read(config.environment)
+          managed = state.dig("resources", "server")
+          unless managed&.fetch("id", nil)
+            raise Errors::UnsafeOperationError.new(
+              "no managed server ID exists in state",
+              hint: "Import and verify the server before attempting destruction."
+            )
+          end
+          validate_confirmation!(confirmation, managed)
+          current = verify_exact_server!(managed)
+          started_at = monotonic_time
+          emit("run_started", command: "server.destroy", environment: config.environment)
+          @provider.delete_server(id: managed.fetch("id")) if current
+          @dns_operation&.rollback
+          record_destruction(managed.fetch("id"))
+          emit("run_finished", status: "success", duration_ms: elapsed_ms(started_at))
+          Result.success(managed.fetch("id"), metadata: { run_id: run_id })
+        rescue StandardError
+          emit("run_finished", status: "failure", duration_ms: 0) if defined?(started_at) && started_at
+          raise
+        end
+
+        def validate_confirmation!(confirmation, managed)
+          return if confirmation == config.server.name
+
+          raise Errors::UnsafeOperationError.new(
+            "server destruction was not confirmed",
+            hint: "Pass --confirm-destroy #{config.server.name} after reviewing the environment.",
+            context: {
+              provider: config.provider.name, environment: config.environment,
+              server: config.server.name, provider_id: managed["id"], recoverable: false
+            }
+          )
+        end
+
+        def verify_exact_server!(managed)
+          current = @provider.find_server_by_id(id: managed.fetch("id"))
+          return unless current
+
+          expected_tags = config.server.tags
+          return current if current.name == config.server.name && (expected_tags - current.tags).empty?
+
+          raise Errors::UnsafeOperationError.new(
+            "managed provider ID points to an unexpected server",
+            hint: "Do not delete by name. Reconcile or import state first."
+          )
+        end
+
+        def record_destruction(id)
+          @state_store.update(config.environment) do |state|
+            state["resources"].clear
+            state["operations"] << { "resource" => "server", "action" => "destroy", "status" => "applied", "id" => id }
+            state
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/workflows/doctor.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "../result"
+require_relative "base"
+
+module Kitsune
+  module Kit
+    module Workflows
+      Check = Data.define(:name, :status, :message, :hint) do
+        def to_h = { name: name, status: status, message: message, hint: hint }
+      end
+
+      class Doctor < Base
+        SUPPORTED_UBUNTU = %w[22.04 24.04].freeze
+
+        def initialize(config:, provider:, state_store:, transport_factory: nil, operations: [],
+                       event_bus: Events::NullBus.new, clock: Clock.new)
+          super(config: config, event_bus: event_bus, clock: clock)
+          @provider = provider
+          @state_store = state_store
+          @transport_factory = transport_factory
+          @operations = operations
+        end
+
+        def call
+          started_at = monotonic_time
+          emit("run_started", command: "doctor", environment: config.environment)
+          checks = local_checks + infrastructure_checks
+          emit_findings(checks)
+          status = checks.any? { |check| check.status == "fail" } ? "failure" : "success"
+          emit("run_finished", status: status, duration_ms: elapsed_ms(started_at))
+          Result.new(status: status.to_sym, value: checks, metadata: { run_id: run_id })
+        end
+
+        private
+
+        def local_checks
+          [runtime_check, configuration_check, ssh_key_check, security_check, provider_check, state_check]
+        end
+
+        def infrastructure_checks
+          @server = find_server
+          values = [server_check]
+          return values unless @server
+
+          values << ssh_connection_check
+          return values unless @transport
+
+          values + [ubuntu_check, sudo_check, docker_check, compose_check, ports_check, drift_check]
+        end
+
+        def emit_findings(checks)
+          checks.reject { |check| check.status == "pass" }.each do |check|
+            emit("warning_emitted", message: "#{check.name}: #{check.message}", hint: check.hint,
+                                    status: check.status)
+          end
+        end
+
+        def runtime_check
+          supported = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.2.0")
+          check("Runtime", supported ? "pass" : "fail", "Ruby #{RUBY_VERSION} on #{RbConfig::CONFIG['host_os']}",
+                supported ? nil : "Install Ruby 3.2 or newer.")
+        end
+
+        def configuration_check = check("Configuration", "pass", "Configuration is valid")
+
+        def ssh_key_check
+          path = config.ssh.key_path
+          unless File.file?(path)
+            return check("SSH key", "fail", "Private key does not exist: #{path}",
+                         "Set ssh.key_path to an existing private key.")
+          end
+
+          mode = File.stat(path).mode & 0o777
+          if mode.anybits?(0o077)
+            return check("SSH key", "warn", format("Private key mode is %<mode>04o", mode: mode),
+                         "Run `chmod 600 #{path}`.")
+          end
+
+          check("SSH key", "pass", "Private key permissions are restricted")
+        rescue SystemCallError => e
+          check("SSH key", "fail", e.message, "Check the configured path and permissions.")
+        end
+
+        def security_check
+          published = %w[postgres redis].select do |type|
+            service = config.services.public_send(type)
+            service.enabled && service.mode == "managed" && service.publish
+          end
+          return check("Security defaults", "pass", "Data services are private") if published.empty?
+
+          check("Security defaults", "warn", "Published services: #{published.join(', ')}",
+                "Confirm every allowed CIDR and prefer private Docker networking.")
+        end
+
+        def provider_check
+          @provider.validate_credentials!
+          check("Provider API", "pass", "DigitalOcean credentials and API access are valid")
+        rescue Errors::Error => e
+          check("Provider API", "fail", e.message, e.hint)
+        end
+
+        def state_check
+          @state = @state_store.read(config.environment)
+          check("State", "pass", "State is readable and schema-compatible")
+        rescue Errors::Error => e
+          check("State", "fail", e.message, e.hint)
+        end
+
+        def find_server
+          @provider.find_server(name: config.server.name, tags: config.server.tags)
+        rescue Errors::Error => e
+          @server_error = e
+          nil
+        end
+
+        def server_check
+          return check("Server", "fail", @server_error.message, @server_error.hint) if @server_error
+          return check("Server", "warn", "Server does not exist", "Run `kit plan`, then `kit apply`.") unless @server
+
+          managed_id = @state&.dig("resources", "server", "id")
+          unless managed_id
+            return check("Server", "warn", "Server exists but is not tracked in local state",
+                         "Restore the state backup before changing or destroying this server.")
+          end
+          if managed_id.to_s != @server.id.to_s
+            return check("Server", "fail", "Provider server does not match the managed ID",
+                         "Reconcile state without deleting either server by name.")
+          end
+
+          status = @server.status == "active" ? "pass" : "warn"
+          check("Server", status, "#{@server.name} is #{@server.status}",
+                status == "pass" ? nil : "Wait for the server to become active.")
+        end
+
+        def ssh_connection_check
+          unless @transport_factory
+            return check("SSH connection", "warn", "SSH adapter is unavailable", "Run doctor through the CLI.")
+          end
+
+          @transport = @transport_factory.bootstrap
+          check("SSH connection", "pass", "Host key and public-key login are verified")
+        rescue Errors::Error => e
+          check("SSH connection", "fail", e.message, e.hint)
+        end
+
+        def ubuntu_check
+          result = @transport.execute("cat", arguments: ["/etc/os-release"], timeout: 15)
+          version = result.stdout[/^VERSION_ID="?([^"\n]+)"?$/, 1]
+          ubuntu = result.stdout.match?(/^ID=ubuntu$/)
+          supported = result.success? && ubuntu && SUPPORTED_UBUNTU.include?(version)
+          check("Remote OS", supported ? "pass" : "fail", "Ubuntu #{version || 'unknown'}",
+                supported ? nil : "Use Ubuntu #{SUPPORTED_UBUNTU.join(' or ')} LTS.")
+        end
+
+        def sudo_check = command_check("Sudo", "sudo", ["-n", "true"], "Passwordless sudo is available")
+
+        def docker_check
+          command_check("Docker", "docker", ["version", "--format", "{{.Server.Version}}"],
+                        "Docker Engine is available", status: "warn", hint: "Run `kit docker install`.")
+        end
+
+        def compose_check
+          command_check("Docker Compose", "docker", ["compose", "version", "--short"],
+                        "Docker Compose v2 is available", status: "warn", hint: "Run `kit docker install`.")
+        end
+
+        def ports_check
+          result = @transport.execute("sudo", arguments: ["ss", "-lntH"], timeout: 15)
+          return check("Ports", "fail", "Unable to inspect listening ports") unless result.success?
+
+          ssh_listening = result.stdout.match?(/:#{Regexp.escape(config.ssh.port.to_s)}\s/)
+          exposed = private_service_ports.select { |port| result.stdout.match?(/(?:0\.0\.0\.0|\[::\]):#{port}\s/) }
+          return check("Ports", "fail", "SSH port #{config.ssh.port} is not listening") unless ssh_listening
+          if exposed.any?
+            return check("Ports", "fail", "Private data ports are publicly listening: #{exposed.join(', ')}",
+                         "Stop the service and inspect its Compose port bindings.")
+          end
+
+          check("Ports", "pass", "SSH is listening and private data ports are not public")
+        end
+
+        def drift_check
+          state = @state || @state_store.read(config.environment)
+          planned = @operations.map { |operation| [operation, operation.plan] }
+          desired_resources = planned.map { |operation, change| state_key_for(operation, change) }
+          drifted = planned.filter_map do |operation, change|
+            change.resource if state.dig("resources", state_key_for(operation, change)) && change.changed?
+          end
+          orphaned = state["resources"].keys - desired_resources
+          findings = drifted + orphaned
+          return check("Drift", "pass", "Managed resources match the desired configuration") if findings.empty?
+
+          check("Drift", "warn", "Review managed-resource drift: #{findings.uniq.join(', ')}",
+                "Run `kit plan`; restore state before adopting or removing existing resources.")
+        rescue Errors::Error => e
+          check("Drift", "fail", e.message, e.hint)
+        end
+
+        def state_key_for(operation, change)
+          operation.respond_to?(:state_key) ? operation.state_key : change.resource
+        end
+
+        def command_check(name, command, arguments, success_message, status: "fail", hint: nil)
+          result = @transport.execute(command, arguments: arguments, timeout: 15)
+          return check(name, "pass", success_message) if result.success?
+
+          check(name, status, "Command failed with status #{result.exit_status}", hint)
+        end
+
+        def private_service_ports
+          %w[postgres redis].filter_map do |type|
+            service = config.services.public_send(type)
+            service.port if service.enabled && service.mode == "managed" && !service.publish
+          end
+        end
+
+        def check(name, status, message, hint = nil)
+          Check.new(name: name, status: status, message: message, hint: hint)
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/workflows/eject_compose.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "tempfile"
+require "yaml"
+require_relative "../errors"
+require_relative "../service_compose"
+
+module Kitsune
+  module Kit
+    module Workflows
+      class EjectCompose
+        TYPES = %w[postgres redis].freeze
+
+        def initialize(root:, config:, type:, config_path: nil)
+          @root = Pathname(root).expand_path
+          @config = config
+          @type = type.to_s
+          @config_path = config_path ? Pathname(config_path).expand_path(@root) : @root.join(".kitsune/config.yml")
+        end
+
+        def call(force: false)
+          @backup_created = false
+          validate_target!(force)
+          content = ServiceCompose.new(config: config, type: type, service: service).generated_content
+          FileUtils.mkdir_p(output_path.dirname, mode: 0o700)
+          FileUtils.cp(config_path, backup_path)
+          @backup_created = true
+          write_atomic(output_path, content, 0o644)
+          update_configuration
+          { compose_file: output_path.to_s, config_file: config_path.to_s, backup_file: backup_path.to_s }
+        rescue StandardError
+          FileUtils.cp(backup_path, config_path) if @backup_created && backup_path.file?
+          raise
+        end
+
+        private
+
+        attr_reader :root, :config, :type, :config_path
+
+        def service = config.services.public_send(type)
+        def output_path = root.join(".kitsune/compose/#{type}.yml")
+        def backup_path = Pathname("#{config_path}.backup")
+
+        def validate_target!(force)
+          raise Errors::ConfigurationError, "unknown service type: #{type}" unless TYPES.include?(type)
+          raise Errors::ConfigurationError, "configuration file does not exist: #{config_path}" unless config_path.file?
+          return if force || (!output_path.exist? && !backup_path.exist? && service.compose.mode == "generated")
+
+          raise Errors::UnsafeOperationError.new(
+            "refusing to replace an existing Compose customization or configuration backup",
+            hint: "Review #{output_path} and #{backup_path}, then repeat with --force if replacement is intentional."
+          )
+        end
+
+        def update_configuration
+          document = YAML.safe_load(config_path.read, permitted_classes: [], permitted_symbols: [], aliases: false)
+          service_config = document.fetch("services").fetch(type)
+          service_config["compose"] = {
+            "mode" => "custom",
+            "file" => ".kitsune/compose/#{type}.yml",
+            "allow_unsafe" => false
+          }
+          write_atomic(config_path, YAML.dump(document), 0o600)
+        rescue KeyError, Psych::Exception => e
+          raise Errors::ConfigurationError, "unable to update configuration for Compose ejection: #{e.message}"
+        end
+
+        def write_atomic(path, content, mode)
+          Tempfile.create([path.basename.to_s, ".tmp"], path.dirname) do |file|
+            file.write(content)
+            file.flush
+            file.fsync
+            File.chmod(mode, file.path)
+            File.rename(file.path, path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/workflows/environment_selection.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "tempfile"
+require_relative "../errors"
+
+module Kitsune
+  module Kit
+    module Workflows
+      class EnvironmentSelection
+        NAME = /\A[a-z0-9][a-z0-9_-]*\z/
+
+        def initialize(root: Dir.pwd)
+          @root = Pathname(root).expand_path
+        end
+
+        def list
+          environments_directory.glob("*.yml").map { |path| path.basename(".yml").to_s }.sort
+        end
+
+        def current(env: ENV)
+          env["KITSUNE_ENV"] || selected_from_file || "development"
+        end
+
+        def use(name)
+          validate_name!(name)
+          unless list.include?(name)
+            raise Errors::ConfigurationError.new(
+              "environment does not exist: #{name}",
+              hint: "Create .kitsune/environments/#{name}.yml, then retry."
+            )
+          end
+
+          FileUtils.mkdir_p(base_directory, mode: 0o700)
+          Tempfile.create(["environment", ".tmp"], base_directory.to_s, mode: 0o600) do |file|
+            file.write("#{name}\n")
+            file.flush
+            file.fsync
+            File.rename(file.path, selection_path)
+          end
+          File.chmod(0o600, selection_path)
+          name
+        end
+
+        private
+
+        attr_reader :root
+
+        def base_directory = root.join(".kitsune")
+        def environments_directory = base_directory.join("environments")
+        def selection_path = base_directory.join("environment")
+
+        def selected_from_file
+          return unless selection_path.file?
+
+          value = selection_path.read.strip
+          validate_name!(value)
+          value
+        end
+
+        def validate_name!(name)
+          return if name.to_s.match?(NAME)
+
+          raise Errors::ConfigurationError, "environment name has an invalid format"
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/workflows/import_server.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../result"
+require_relative "base"
+
+module Kitsune
+  module Kit
+    module Workflows
+      class ImportServer < Base
+        def initialize(config:, provider:, state_store:, event_bus: Events::NullBus.new, clock: Clock.new)
+          super(config: config, event_bus: event_bus, clock: clock)
+          @provider = provider
+          @state_store = state_store
+        end
+
+        def call(provider_id:, confirmation:)
+          validate_inputs!(provider_id, confirmation)
+          @state_store.with_execution_lock(config.environment) do
+            import_locked(provider_id.to_s)
+          end
+        end
+
+        private
+
+        def validate_inputs!(provider_id, confirmation)
+          unless provider_id.to_s.match?(/\A[0-9]+\z/)
+            raise Errors::ConfigurationError.new(
+              "a numeric provider ID is required for server import",
+              hint: "Pass --provider-id after copying the exact Droplet ID from the DigitalOcean control panel."
+            )
+          end
+          return if confirmation == config.server.name
+
+          raise Errors::UnsafeOperationError.new(
+            "server import was not confirmed",
+            hint: "Pass --confirm-import #{config.server.name} only after checking the exact provider ID."
+          )
+        end
+
+        def import_locked(provider_id)
+          state = @state_store.read(config.environment)
+          existing_id = state.dig("resources", "server", "id")
+          return Result.success(existing_id, metadata: { unchanged: true }) if existing_id.to_s == provider_id
+          if existing_id
+            raise Errors::UnsafeOperationError.new(
+              "state already tracks a different server",
+              hint: "Restore/reconcile the existing state instead of replacing its provider ID."
+            )
+          end
+
+          server = @provider.find_server_by_id(id: provider_id)
+          unless server
+            raise Errors::ProviderError.new(
+              "server does not exist for provider ID #{provider_id}",
+              hint: "Copy the exact Droplet ID from DigitalOcean and retry."
+            )
+          end
+          verify_identity!(server)
+          record(server)
+          Result.success(server, metadata: { imported: true })
+        end
+
+        def verify_identity!(server)
+          differences = {
+            name: [server.name, config.server.name],
+            region: [server.region, config.server.region],
+            size: [server.size, config.server.size],
+            image: [server.image, config.server.image],
+            tags: [server.tags, config.server.tags],
+            status: [server.status, "active"]
+          }
+          differences.delete_if do |field, (actual, desired)|
+            field == :tags ? (desired - Array(actual)).empty? : actual == desired
+          end
+          return if differences.empty? && server.public_ip
+
+          differences[:public_ip] = [server.public_ip, "required"] unless server.public_ip
+          raise Errors::UnsafeOperationError.new(
+            "provider server does not match the configured environment",
+            hint: "Do not import it. Correct configuration or recover the original state backup.",
+            context: { provider_id: server.id, differences: differences }
+          )
+        end
+
+        def record(server)
+          @state_store.update(config.environment) do |state|
+            state["resources"]["server"] = server.to_h.transform_keys(&:to_s).merge(
+              "provider" => config.provider.name
+            )
+            state["operations"] << {
+              "resource" => "server.#{config.server.name}", "action" => "import", "status" => "applied"
+            }
+            state
+          end
+        end
+      end
+    end
+  end
+end