kitsune-kit 0.4.0 → 0.5.0

data/lib/kitsune/kit/secret_store.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "secret_stores/store"
+
+module Kitsune
+  module Kit
+    module SecretStores
+      class Environment < Store
+        def initialize(env: ENV, filter: nil)
+          super()
+          @env = env
+          @filter = filter
+        end
+
+        def fetch(name, required: true)
+          value = @env.fetch(name.to_s, "")
+          if required && value.empty?
+            raise Errors::ConfigurationError.new(
+              "required secret #{name} is not set",
+              hint: "Export #{name} before running this command."
+            )
+          end
+          @filter&.register(value)
+          value
+        end
+
+        def configured?(name) = !@env.fetch(name.to_s, "").empty?
+      end
+    end
+  end
+end

data/lib/kitsune/kit/secret_stores/store.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module SecretStores
+      class Store
+        def fetch(name, required: true) = raise NotImplementedError
+        def configured?(name) = raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/kitsune/kit/service_compose.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Kitsune
+  module Kit
+    class ServiceCompose
+      def initialize(config:, type:, service:)
+        @config = config
+        @type = type
+        @service = service
+      end
+
+      def content = YAML.dump(document)
+      def env_content(password) = "#{@service.password_env}=#{JSON.generate(password)}\n"
+
+      private
+
+      def document
+        {
+          "name" => project_name,
+          "services" => { @type => service_definition },
+          "volumes" => { "data" => nil },
+          "networks" => { "private" => { "external" => true, "name" => "kitsune-private" } }
+        }
+      end
+
+      def service_definition
+        definition = @type == "postgres" ? postgres : redis
+        definition["ports"] = ["#{@service.bind}:#{@service.port}:#{container_port}"] if @service.publish
+        definition
+      end
+
+      def postgres
+        {
+          "image" => @service.image,
+          "restart" => "unless-stopped",
+          "environment" => {
+            "POSTGRES_DB" => database,
+            "POSTGRES_USER" => "postgres",
+            "POSTGRES_PASSWORD" => interpolation
+          },
+          "volumes" => ["data:/var/lib/postgresql/data"],
+          "networks" => ["private"],
+          "healthcheck" => healthcheck("pg_isready -U postgres -d #{database}")
+        }
+      end
+
+      def redis
+        {
+          "image" => @service.image,
+          "restart" => "unless-stopped",
+          "environment" => { "REDIS_PASSWORD" => interpolation },
+          "command" => ["sh", "-ec", 'exec redis-server --appendonly yes --requirepass "$$REDIS_PASSWORD"'],
+          "volumes" => ["data:/data"],
+          "networks" => ["private"],
+          "healthcheck" => healthcheck('REDISCLI_AUTH="$${REDIS_PASSWORD}" redis-cli ping | grep -Fxq PONG')
+        }
+      end
+
+      def healthcheck(command)
+        { "test" => ["CMD-SHELL", command], "interval" => "10s", "timeout" => "5s", "retries" => 12 }
+      end
+
+      def project_name = "kitsune-#{@config.environment}-#{@type}"
+      def database = "app_#{@config.environment.tr('-', '_')}"
+      def container_port = @type == "postgres" ? 5432 : 6379
+      def interpolation = "${#{@service.password_env}}"
+    end
+  end
+end

data/lib/kitsune/kit/state_store.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "pathname"
+require "tempfile"
+require "time"
+require_relative "errors"
+require_relative "state_stores/store"
+
+module Kitsune
+  module Kit
+    class StateStore < StateStores::Store
+      SCHEMA_VERSION = 1
+
+      def initialize(root: Dir.pwd)
+        super()
+        @directory = Pathname(root).expand_path.join(".kitsune/state")
+      end
+
+      def read(environment)
+        path = state_path(environment)
+        return empty_state(environment) unless path.file?
+
+        with_lock(environment, shared: true) do
+          parsed = JSON.parse(path.read)
+          validate!(parsed, environment)
+          parsed
+        end
+      rescue JSON::ParserError => e
+        raise Errors::ConfigurationError.new(
+          "state file is invalid JSON: #{path}",
+          hint: "Restore the state backup or import the environment again.",
+          context: { cause: e.message }
+        )
+      end
+
+      def update(environment)
+        with_lock(environment) do
+          current = read_without_lock(environment)
+          updated = yield(deep_copy(current))
+          updated["updated_at"] = Time.now.utc.iso8601(6)
+          validate!(updated, environment)
+          write_atomically(state_path(environment), JSON.pretty_generate(updated) << "\n")
+          deep_copy(updated)
+        end
+      end
+
+      def write(environment, state)
+        update(environment) { state }
+      end
+
+      def delete(environment)
+        with_lock(environment) do
+          next unless state_path(environment).file?
+
+          state_path(environment).delete
+          true
+        end
+      end
+
+      def with_execution_lock(environment)
+        FileUtils.mkdir_p(@directory, mode: 0o700)
+        path = @directory.join("#{safe_environment(environment)}.operation.lock")
+        File.open(path, File::RDWR | File::CREAT, 0o600) do |file|
+          locked = file.flock(File::LOCK_EX | File::LOCK_NB)
+          unless locked
+            raise Errors::UnsafeOperationError.new(
+              "another mutating operation is active for #{environment}",
+              hint: "Wait for it to finish or stop it safely before retrying."
+            )
+          end
+          yield
+        ensure
+          file.flock(File::LOCK_UN) if locked
+        end
+      end
+
+      private
+
+      def empty_state(environment)
+        {
+          "version" => SCHEMA_VERSION,
+          "environment" => environment.to_s,
+          "updated_at" => nil,
+          "resources" => {},
+          "operations" => [],
+          "runs" => {}
+        }
+      end
+
+      def state_path(environment) = @directory.join("#{safe_environment(environment)}.json")
+      def lock_path(environment) = @directory.join("#{safe_environment(environment)}.lock")
+
+      def safe_environment(environment)
+        value = environment.to_s
+        return value if value.match?(/\A[a-zA-Z0-9_-]+\z/)
+
+        raise Errors::ConfigurationError, "environment name has an invalid format"
+      end
+
+      def with_lock(environment, shared: false)
+        FileUtils.mkdir_p(@directory, mode: 0o700)
+        File.open(lock_path(environment), File::RDWR | File::CREAT, 0o600) do |file|
+          file.flock(shared ? File::LOCK_SH : File::LOCK_EX)
+          yield
+        ensure
+          file.flock(File::LOCK_UN)
+        end
+      end
+
+      def read_without_lock(environment)
+        path = state_path(environment)
+        return empty_state(environment) unless path.file?
+
+        parsed = JSON.parse(path.read)
+        validate!(parsed, environment)
+        parsed
+      rescue JSON::ParserError => e
+        raise Errors::ConfigurationError.new("state file is invalid JSON: #{path}", context: { cause: e.message })
+      end
+
+      def validate!(state, environment)
+        raise Errors::ConfigurationError, "state must be an object" unless state.is_a?(Hash)
+        unless state["version"] == SCHEMA_VERSION
+          raise Errors::ConfigurationError.new(
+            "unsupported state schema version #{state['version'].inspect}; expected #{SCHEMA_VERSION}",
+            hint: "Use a compatible Kitsune Kit version; do not edit IDs manually. Preserve this file and its backup."
+          )
+        end
+        raise Errors::ConfigurationError, "state environment mismatch" unless state["environment"] == environment.to_s
+        raise Errors::ConfigurationError, "state resources must be an object" unless state["resources"].is_a?(Hash)
+        raise Errors::ConfigurationError, "state operations must be an array" unless state["operations"].is_a?(Array)
+        raise Errors::ConfigurationError, "state runs must be an object" unless state["runs"].is_a?(Hash)
+
+        state
+      end
+
+      def write_atomically(path, content)
+        FileUtils.mkdir_p(path.dirname, mode: 0o700)
+        backup = Pathname("#{path}.backup")
+        if path.file?
+          FileUtils.cp(path, backup)
+          File.chmod(0o600, backup)
+        end
+        Tempfile.create([path.basename.to_s, ".tmp"], path.dirname.to_s, mode: 0o600) do |temp|
+          temp.write(content)
+          temp.flush
+          temp.fsync
+          File.rename(temp.path, path)
+          File.chmod(0o600, path)
+        end
+      end
+
+      def deep_copy(value) = Marshal.load(Marshal.dump(value))
+    end
+  end
+end

data/lib/kitsune/kit/state_stores/store.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module StateStores
+      class Store
+        def read(environment) = raise NotImplementedError
+        def update(environment) = raise NotImplementedError
+        def write(environment, state) = raise NotImplementedError
+        def delete(environment) = raise NotImplementedError
+        def with_execution_lock(environment) = raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/kitsune/kit/tui/actions.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module Tui
+      class Actions
+        def initialize(application:, cancellation: Cancellation.new)
+          @application = application
+          @cancellation = cancellation
+          @last_plan = nil
+        end
+
+        def status
+          Workflows::InspectEnvironment.new(
+            config: app.config, provider: app.provider, state_store: app.state_store, event_bus: app.event_bus
+          ).call
+        end
+
+        def plan
+          workflow = Workflows::BuildPlan.new(config: app.config, operations: app.operations,
+                                              event_bus: app.event_bus)
+          workflow.call.tap do |result|
+            @last_plan = result.value
+          end
+        end
+
+        def doctor
+          Workflows::Doctor.new(
+            config: app.config,
+            provider: app.provider,
+            state_store: app.state_store,
+            transport_factory: app.transport_factory,
+            operations: app.operations,
+            event_bus: app.event_bus
+          ).call
+        end
+
+        def apply
+          @last_plan ||= plan.value
+          raise Errors::UnsafeOperationError, "the plan contains destructive changes" if @last_plan.destructive?
+          return Result.success([], metadata: { unchanged: true }) unless @last_plan.changed?
+
+          Workflows::ApplyPlan.new(
+            config: app.config, operations: app.operations, state_store: app.state_store, event_bus: app.event_bus,
+            cancellation: @cancellation
+          ).call(plan: @last_plan)
+        ensure
+          @last_plan = nil
+          reset_cancellation
+        end
+
+        def resume
+          Workflows::ApplyPlan.new(
+            config: app.config, operations: app.operations, state_store: app.state_store, event_bus: app.event_bus,
+            cancellation: @cancellation
+          ).call(resume_from: true)
+        ensure
+          reset_cancellation
+        end
+
+        def cancel = @cancellation.cancel!
+
+        private
+
+        attr_reader :application
+        alias app application
+
+        def reset_cancellation = @cancellation = Cancellation.new
+      end
+    end
+  end
+end

data/lib/kitsune/kit/tui/application.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module Tui
+      class Application
+        def initialize(store:, controller:, renderer: Renderer.new, terminal: Terminal.new)
+          @store = store
+          @controller = controller
+          @renderer = renderer
+          @terminal = terminal
+        end
+
+        def call
+          terminal.run do
+            controller.start
+            until controller.exit_requested
+              width, height = terminal.size
+              store.resize(width, height)
+              terminal.draw(renderer.render(store.snapshot))
+              controller.handle(terminal.read_key)
+            end
+          end
+          0
+        ensure
+          controller.wait
+        end
+
+        private
+
+        attr_reader :store, :controller, :renderer, :terminal
+      end
+    end
+  end
+end

data/lib/kitsune/kit/tui/controller.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module Tui
+      class Controller
+        CONFIRMATIONS = {
+          apply: "Apply the visible plan?",
+          resume: "Resume the latest incomplete run?"
+        }.freeze
+        SCREEN_KEYS = { "p" => %i[plan plan], "d" => %i[doctor doctor] }.freeze
+        SIMPLE_KEYS = { "l" => :logs, "?" => :help, "a" => :apply, "r" => :resume }.freeze
+        NAVIGATION_KEYS = { "j" => 1, down: 1, "k" => -1, up: -1 }.freeze
+        SCROLL_KEYS = { page_up: 5, page_down: -5 }.freeze
+        SCREENS = %i[dashboard plan doctor logs help].freeze
+
+        attr_reader :exit_requested
+
+        def initialize(store:, actions:)
+          @store = store
+          @actions = actions
+          @exit_requested = false
+          @worker = nil
+          @pending_action = nil
+        end
+
+        def handle(key)
+          return if key.nil?
+          return handle_modal(key) if store.snapshot.modal
+          return run_screen_action(key) if SCREEN_KEYS.key?(key)
+          return handle_simple(SIMPLE_KEYS.fetch(key)) if SIMPLE_KEYS.key?(key)
+          return navigate(NAVIGATION_KEYS.fetch(key)) if NAVIGATION_KEYS.key?(key)
+          return store.scroll(SCROLL_KEYS.fetch(key)) if SCROLL_KEYS.key?(key)
+
+          case key
+          when "q" then request_exit
+          when "\u0003" then cancel_or_exit
+          when "\t" then cycle_screen
+          end
+        end
+
+        def busy? = @worker&.alive? || false
+
+        def start = run(:status, screen: :dashboard)
+
+        def wait
+          @worker&.join
+        end
+
+        private
+
+        attr_reader :store, :actions
+
+        def request_exit
+          if busy?
+            store.modal(message: "An operation is active. Quit after it finishes?", action: :quit)
+          else
+            @exit_requested = true
+          end
+        end
+
+        def cancel_or_exit
+          return @exit_requested = true unless busy?
+
+          actions.cancel
+          store.handle(
+            Events::Event.build("warning_emitted", run_id: "tui", message: "Cancellation requested")
+          )
+        end
+
+        def move(delta)
+          state = store.snapshot
+          return if state.resources.empty?
+
+          store.select((state.selected_resource + delta) % state.resources.length)
+        end
+
+        def navigate(delta)
+          return store.scroll(-delta) if store.snapshot.screen == :logs
+
+          move(delta)
+        end
+
+        def cycle_screen
+          current = SCREENS.index(store.snapshot.screen) || 0
+          store.show(SCREENS[(current + 1) % SCREENS.length])
+        end
+
+        def toggle_help
+          state = store.snapshot
+          store.show(state.screen == :help ? :dashboard : :help)
+        end
+
+        def run_screen_action(key)
+          action, screen = SCREEN_KEYS.fetch(key)
+          run(action, screen: screen)
+        end
+
+        def handle_simple(action)
+          case action
+          when :logs then store.show(:logs)
+          when :help then toggle_help
+          else confirm(action)
+          end
+        end
+
+        def confirm(action)
+          return busy_notification if busy?
+
+          @pending_action = action
+          store.modal(message: CONFIRMATIONS.fetch(action), action: action)
+        end
+
+        def handle_modal(key)
+          modal = store.snapshot.modal
+          if key == "y"
+            store.modal(nil)
+            return @exit_requested = true if modal[:action] == :quit
+
+            run(modal[:action], screen: modal[:action] == :apply ? :plan : :logs)
+          elsif ["n", :escape, "q"].include?(key)
+            store.modal(nil)
+          end
+        end
+
+        def run(action, screen:)
+          return busy_notification if busy?
+
+          store.show(screen)
+          store.running(true)
+          @worker = Thread.new do
+            result = actions.public_send(action)
+            update_resources(result.value) if action == :status
+            store.show(screen, result: result.value)
+          rescue StandardError => e
+            store.modal(nil)
+            store.show(:logs)
+            store.handle(
+              Events::Event.build("operation_failed", run_id: "tui", resource: action.to_s,
+                                                      summary: action.to_s, message: e.message)
+            )
+          ensure
+            store.running(false)
+          end
+        end
+
+        def update_resources(status)
+          resources = status.managed_resources.map do |name, value|
+            state = value.is_a?(Hash) && value["managed"] == false ? "drift" : "managed"
+            { name: name, status: state }
+          end
+          resources.unshift(name: "server", status: status.server ? status.server.status : "missing")
+          store.resources = resources
+        end
+
+        def busy_notification
+          store.handle(Events::Event.build("warning_emitted", run_id: "tui", message: "Another operation is active"))
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/tui/renderer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module Tui
+      class Renderer
+        MIN_WIDTH = 70
+        MIN_HEIGHT = 18
+
+        def render(state)
+          width, height = state.terminal_size
+          return small_terminal(width, height) if width < MIN_WIDTH || height < MIN_HEIGHT
+
+          body = screen_lines(state, width, height - 4)
+          lines = [top_border(state, width), *body, footer(state, width), bottom_border(width)]
+          fit(lines, width, height)
+        end
+
+        private
+
+        def screen_lines(state, width, height)
+          return modal_lines(state, width, height) if state.modal
+
+          case state.screen
+          when :dashboard then dashboard(state, width, height)
+          when :plan then plan(state, width, height)
+          when :doctor then doctor(state, width, height)
+          when :logs then logs(state, width, height)
+          when :help then help_lines
+          else [" Unknown screen "]
+          end
+        end
+
+        def dashboard(state, width, height)
+          left_width = [(width * 0.34).floor, 24].max
+          resources = state.resources.empty? ? [{ name: "No managed resources", status: "pending" }] : state.resources
+          left = resources.each_with_index.map do |resource, index|
+            marker = index == state.selected_resource ? ">" : " "
+            "#{marker} #{resource[:name].to_s.ljust(left_width - 13)} #{resource[:status]}"
+          end
+          right = ["Details", "", "Environment: #{state.environment}"]
+          right.concat(state.operations.last([height - 6, 0].max).map { |operation| operation_line(operation) })
+          columns(left, right, left_width, width, height)
+        end
+
+        def plan(state, width, _height)
+          plan = state.result
+          return [" Plan has not been built. Press p. "] unless plan
+
+          [" Plan for #{plan.environment}", ""] + plan.changes.map do |change|
+            marker = { "create" => "+", "update" => "~", "delete" => "-", "no_change" => "=" }.fetch(change.action)
+            truncate(" #{marker} #{change.summary}", width - 2)
+          end + ["", " #{plan.changed_count} change(s)"]
+        end
+
+        def doctor(state, width, _height)
+          checks = state.result
+          return [" Doctor has not run. Press d. "] unless checks
+
+          checks.flat_map do |check|
+            lines = [truncate(" #{check.status.upcase.ljust(5)} #{check.name}: #{check.message}", width - 2)]
+            lines << truncate("       Fix: #{check.hint}", width - 2) if check.hint
+            lines
+          end
+        end
+
+        def logs(state, width, height)
+          available = [height - 2, 0].max
+          end_index = [state.logs.length - state.scroll_offset, 0].max
+          start_index = [end_index - available, 0].max
+          visible = state.logs[start_index...end_index] || []
+          [" Logs", ""] + visible.map { |line| truncate(" #{line}", width - 2) }
+        end
+
+        def help_lines
+          [
+            " Keyboard shortcuts", "", " j/k or arrows  Select resource", " p              Build plan",
+            " a              Apply the visible plan", " d              Run doctor", " r              Resume failed run",
+            " l              Show logs", " Tab            Next screen", " PgUp/PgDn      Scroll logs",
+            " ?              Toggle help", " q              Quit",
+            " Ctrl+C         Cancel/quit"
+          ]
+        end
+
+        def modal_lines(state, width, height)
+          message = state.modal[:message]
+          padding = [((height - 5) / 2), 0].max
+          ([""] * padding) + [center("Confirmation", width - 2), "", center(message, width - 2),
+                              center("Press y to confirm or n/Esc to cancel", width - 2)]
+        end
+
+        def columns(left, right, left_width, width, height)
+          right_width = width - left_width - 4
+          Array.new(height) do |index|
+            " #{truncate(left[index].to_s, left_width).ljust(left_width)}│ #{truncate(right[index].to_s, right_width)}"
+          end
+        end
+
+        def operation_line(operation)
+          duration = operation[:duration_ms] ? " #{operation[:duration_ms]}ms" : ""
+          progress = operation[:percent] ? " #{operation[:percent]}%" : ""
+          "#{operation[:status].to_s.ljust(9)} #{operation[:summary]}#{progress}#{duration}"
+        end
+
+        def top_border(state, width)
+          title = " Kitsune Kit · #{state.environment} · #{state.screen} "
+          "┌#{title}#{'─' * [width - title.length - 2, 0].max}┐"
+        end
+
+        def footer(state, width)
+          status = state.running ? "running" : (state.notification || "ready")
+          content = truncate("├─ p plan  a apply  d doctor  r resume  l logs  ? help  q quit · #{status} ", width - 1)
+          "#{content.ljust(width - 1, '─')}┤"
+        end
+
+        def bottom_border(width) = "└#{'─' * (width - 2)}┘"
+
+        def small_terminal(width, height)
+          fit(["Kitsune Kit", "", "Terminal too small (#{width}x#{height}).", "Minimum: #{MIN_WIDTH}x#{MIN_HEIGHT}.",
+               "Resize or press q to quit."], width, height)
+        end
+
+        def fit(lines, width, height)
+          lines.first(height).map { |line| truncate(line, width).ljust(width) }.then do |visible|
+            (visible + Array.new([height - visible.length, 0].max, " " * width)).join("\n")
+          end
+        end
+
+        def center(value, width) = value.to_s.center(width)
+        def truncate(value, width) = value.length > width ? "#{value[0, [width - 1, 0].max]}…" : value
+      end
+    end
+  end
+end