kitsune-kit 0.4.1 → 0.5.0

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/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

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require_relative "../errors"
+
+module Kitsune
+  module Kit
+    module Workflows
+      class InitializeProject
+        CONFIG = <<~YAML
+          version: 1
+          provider:
+            name: digitalocean
+            token_env: DO_API_TOKEN
+
+          server:
+            name: myapp-development
+            region: sfo3
+            size: s-1vcpu-1gb
+            image: ubuntu-24-04-x64
+            ssh_key_id: replace-with-digitalocean-key-id
+            tags:
+              - kitsune-managed
+
+          ssh:
+            user: deploy
+            port: 22
+            key_path: ~/.ssh/id_ed25519
+            allowed_cidrs: []
+
+          services:
+            postgres:
+              enabled: false
+              mode: managed
+              host:
+              image: postgres:17
+              publish: false
+              bind: 127.0.0.1
+              allowed_cidrs: []
+              port: 5432
+              password_env: POSTGRES_PASSWORD
+            redis:
+              enabled: false
+              mode: managed
+              host:
+              image: redis:7.2
+              publish: false
+              bind: 127.0.0.1
+              allowed_cidrs: []
+              port: 6379
+              password_env: REDIS_PASSWORD
+
+          system:
+            swap_size_gb: 2
+            swap_swappiness: 10
+            unattended_upgrades: true
+            metrics: false
+            metrics_installer_sha256:
+
+          dns:
+            domains: []
+            ttl: 3600
+        YAML
+
+        ENVIRONMENT = <<~YAML
+          version: 1
+          server:
+            name: myapp-development
+        YAML
+
+        def initialize(root: Dir.pwd)
+          @root = Pathname(root).expand_path
+        end
+
+        def call(force: false)
+          base = @root.join(".kitsune")
+          files = {
+            base.join("config.yml") => CONFIG,
+            base.join("environments/development.yml") => ENVIRONMENT,
+            base.join("environment") => "development\n"
+          }
+          existing = files.keys.select(&:exist?)
+          if existing.any? && !force
+            raise Errors::UnsafeOperationError.new(
+              "Kitsune Kit configuration already exists",
+              hint: "Use `kit init --force` only if replacing these files is intentional.",
+              context: { files: existing.map(&:to_s) }
+            )
+          end
+
+          files.each do |path, content|
+            FileUtils.mkdir_p(path.dirname, mode: 0o700)
+            path.write(content)
+            File.chmod(0o600, path)
+          end
+          ensure_gitignore
+          files.keys.map(&:to_s)
+        end
+
+        private
+
+        def ensure_gitignore
+          path = @root.join(".gitignore")
+          lines = path.file? ? path.readlines(chomp: true) : []
+          additions = [
+            "/.kitsune/state/",
+            "/.kitsune/logs/",
+            "/.kitsune/support/",
+            "/.kitsune/environment",
+            "/.kitsune/known_hosts"
+          ] - lines
+          return if additions.empty?
+
+          separator = lines.empty? || lines.last.empty? ? "" : "\n"
+          File.open(path, "a", 0o644) { |file| file.write("#{separator}#{additions.join("\n")}\n") }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../result"
+require_relative "base"
+
+module Kitsune
+  module Kit
+    module Workflows
+      EnvironmentStatus = Data.define(:environment, :server, :managed_resources, :last_operations) do
+        def to_h
+          {
+            environment: environment,
+            server: server&.to_h,
+            managed_resources: managed_resources,
+            last_operations: last_operations
+          }
+        end
+      end
+
+      class InspectEnvironment < 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
+          started_at = monotonic_time
+          emit("run_started", command: "inspect", environment: config.environment)
+          state = @state_store.read(config.environment)
+          server = @provider.find_server(name: config.server.name, tags: config.server.tags)
+          value = EnvironmentStatus.new(
+            environment: config.environment,
+            server: server,
+            managed_resources: state["resources"],
+            last_operations: state["operations"].last(20)
+          )
+          emit("run_finished", status: "success", duration_ms: elapsed_ms(started_at))
+          Result.success(value, metadata: { run_id: run_id })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../result"
+require_relative "base"
+
+module Kitsune
+  module Kit
+    module Workflows
+      class Rollback < Base
+        def initialize(config:, operations:, state_store: nil, event_bus: Events::NullBus.new, clock: Clock.new)
+          super(config: config, event_bus: event_bus, clock: clock)
+          @operations = operations
+          @state_store = state_store
+        end
+
+        def call
+          return call_unlocked unless @state_store
+
+          @state_store.with_execution_lock(config.environment) { call_unlocked }
+        end
+
+        private
+
+        def call_unlocked
+          started_at = monotonic_time
+          emit("run_started", command: "rollback", environment: config.environment)
+          rolled_back = @operations.reverse.filter_map { |operation| rollback_operation(operation) }
+          emit("run_finished", status: "success", duration_ms: elapsed_ms(started_at))
+          Result.success(rolled_back, metadata: { run_id: run_id })
+        rescue StandardError
+          emit("run_finished", status: "failure", duration_ms: elapsed_ms(started_at))
+          raise
+        end
+
+        def rollback_operation(operation)
+          return unless operation.respond_to?(:rollback)
+
+          started_at = monotonic_time
+          emit("operation_started", resource: operation.resource, summary: "Rollback #{operation.resource}",
+                                    action: "rollback")
+          changed = operation.rollback
+          emit(
+            "operation_succeeded",
+            resource: operation.resource,
+            summary: changed ? "Rolled back #{operation.resource}" : "#{operation.resource} was not managed",
+            action: "rollback",
+            duration_ms: elapsed_ms(started_at)
+          )
+          operation.resource if changed
+        end
+      end
+    end
+  end
+end