kitsune-kit 0.4.1 → 0.6.0

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

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module Tui
+      State = Data.define(
+        :screen, :environment, :resources, :selected_resource, :operations, :logs, :modal, :notification,
+        :running, :terminal_size, :result, :scroll_offset
+      ) do
+        def self.initial(environment:, terminal_size: [100, 30])
+          new(screen: :dashboard, environment: environment, resources: [], selected_resource: 0, operations: [],
+              logs: [], modal: nil, notification: nil, running: false, terminal_size: terminal_size, result: nil,
+              scroll_offset: 0)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "state"
+
+module Kitsune
+  module Kit
+    module Tui
+      class Store
+        MAX_LOGS = 200
+
+        def initialize(environment:, secret_filter: SecretFilter.new, terminal_size: [100, 30])
+          @state = State.initial(environment: environment, terminal_size: terminal_size)
+          @secret_filter = secret_filter
+          @mutex = Mutex.new
+        end
+
+        def snapshot = @mutex.synchronize { @state }
+
+        def handle(event)
+          data = @secret_filter.filter(event.data)
+          mutate do |state|
+            operations = update_operations(state.operations, event.type, data)
+            logs = append_log(state.logs, event.type, data)
+            state.with(operations: operations, logs: logs, running: running_for(event.type, state.running),
+                       notification: notification_for(event.type, data, state.notification))
+          end
+        end
+
+        def show(screen, result: nil)
+          mutate { |state| state.with(screen: screen, result: result, modal: nil, scroll_offset: 0) }
+        end
+
+        def resize(width, height) = mutate { |state| state.with(terminal_size: [width, height]) }
+        def select(index) = mutate { |state| state.with(selected_resource: index) }
+        def modal(value) = mutate { |state| state.with(modal: value) }
+        def running(value) = mutate { |state| state.with(running: value) }
+
+        def scroll(delta)
+          mutate do |state|
+            maximum = [state.logs.length - 1, 0].max
+            state.with(scroll_offset: (state.scroll_offset + delta).clamp(0, maximum))
+          end
+        end
+
+        def resources=(values)
+          mutate { |state| state.with(resources: values, selected_resource: 0) }
+        end
+
+        private
+
+        def mutate
+          @mutex.synchronize { @state = yield(@state) }
+        end
+
+        def update_operations(operations, type, data)
+          return operations unless type.start_with?("operation_")
+
+          item = {
+            resource: data[:resource], summary: data[:summary], status: type.delete_prefix("operation_"),
+            duration_ms: data[:duration_ms], message: data[:message], percent: data[:percent]
+          }
+          operations.reject { |operation| operation[:resource] == item[:resource] } + [item]
+        end
+
+        def append_log(logs, type, data)
+          message = data[:message] || data[:summary]
+          return logs unless message
+
+          (logs + ["#{type}: #{message}"]).last(MAX_LOGS)
+        end
+
+        def running_for(type, current)
+          return true if type == "run_started"
+          return false if type == "run_finished"
+
+          current
+        end
+
+        def notification_for(type, data, current)
+          return data[:message] if %w[operation_failed warning_emitted].include?(type)
+          return "Run finished: #{data[:status]}" if type == "run_finished"
+
+          current
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "io/wait"
+
+module Kitsune
+  module Kit
+    module Tui
+      class Terminal
+        ALT_SCREEN = "\e[?1049h"
+        MAIN_SCREEN = "\e[?1049l"
+        DISABLE_WRAP = "\e[?7l"
+        ENABLE_WRAP = "\e[?7h"
+
+        def initialize(input: $stdin, output: $stdout)
+          @input = input
+          @output = output
+        end
+
+        def tty? = input.tty? && output.tty?
+
+        def run
+          raise Errors::ConfigurationError, "the TUI requires an interactive terminal" unless tty?
+
+          enter
+          yield self
+        ensure
+          restore
+        end
+
+        def size
+          rows, columns = output.winsize
+          [columns, rows]
+        rescue SystemCallError, NoMethodError
+          [100, 30]
+        end
+
+        def draw(content)
+          frame = content.lines(chomp: true).each_with_index.map do |line, index|
+            "\e[#{index + 1};1H#{line}"
+          end.join
+          output.write(frame)
+          output.flush
+        end
+
+        def read_key(timeout: 0.1)
+          return unless input.wait_readable(timeout)
+
+          first = input.read_nonblock(1)
+          return first unless first == "\e"
+
+          sequence = first.dup
+          sequence << input.read_nonblock(1) while sequence.length < 6 && input.wait_readable(0.005)
+          { "\e[A" => :up, "\e[B" => :down, "\e[5~" => :page_up, "\e[6~" => :page_down }
+            .fetch(sequence, :escape)
+        rescue IO::WaitReadable
+          nil
+        end
+
+        private
+
+        attr_reader :input, :output
+
+        def enter
+          @original_console_mode = input.console_mode
+          input.raw!
+          @active = true
+          output.write("#{ALT_SCREEN}#{DISABLE_WRAP}\e[?25l\e[2J\e[H")
+          output.flush
+        end
+
+        def restore
+          return unless @active
+
+          restore_console
+          restore_screen
+          @active = false
+        end
+
+        def restore_console
+          input.console_mode = @original_console_mode if @original_console_mode
+        rescue SystemCallError, IOError
+          nil
+        end
+
+        def restore_screen
+          output.write("#{ENABLE_WRAP}\e[?25h#{MAIN_SCREEN}")
+          output.flush
+        rescue SystemCallError, IOError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/version.rb

@@ -2,6 +2,6 @@
 
 module Kitsune
   module Kit
-    VERSION = "0.4.1"
+    VERSION = "0.6.0"
   end
 end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../result"
+require_relative "../run_journal"
+require_relative "base"
+
+module Kitsune
+  module Kit
+    module Workflows
+      class ApplyPlan < Base
+        def initialize(config:, operations:, state_store: nil, cancellation: Cancellation.new,
+                       event_bus: Events::NullBus.new, clock: Clock.new)
+          super(config: config, event_bus: event_bus, clock: clock)
+          @operations = operations
+          @cancellation = cancellation
+          @state_store = state_store
+          @journal = RunJournal.new(
+            state_store: state_store,
+            environment: config.environment,
+            run_id: run_id,
+            clock: -> { clock.now }
+          )
+        end
+
+        def call(plan: nil, resume_from: nil)
+          return call_unlocked(plan: plan, resume_from: resume_from) unless @state_store
+
+          @state_store.with_execution_lock(config.environment) do
+            call_unlocked(plan: plan, resume_from: resume_from)
+          end
+        end
+
+        private
+
+        def call_unlocked(plan:, resume_from:)
+          started_at = monotonic_time
+          journal_started = false
+          execution = build_execution(plan, resume_from)
+          emit("run_started", command: "apply", environment: config.environment, resumed_from: execution[:source_id])
+          @journal.start(changes: execution[:changes].map(&:to_h), resumed_from: execution[:source_id])
+          journal_started = true
+          @last_confirmed = nil
+          results = execute(execution)
+          finish("success", started_at)
+          Result.success(results, metadata: { run_id: run_id, resumed_from: execution[:source_id] })
+        rescue StandardError => e
+          if journal_started
+            emit_recovery_guidance
+            finish(failure_status(e), started_at, error: error_code(e))
+          end
+          raise
+        end
+
+        def build_execution(plan, resume_from)
+          return fresh_execution(plan) unless resume_from
+
+          source_id, source = @journal.resumable(resume_from == true ? nil : resume_from)
+          changes = Plan.from_h(environment: config.environment, changes: source["changes"]).changes
+          validate_operation_set!(changes)
+          completed = source["steps"].filter_map { |resource, step| resource if step["status"] == "success" }
+          { source_id: source_id, changes: changes, completed: completed }
+        end
+
+        def fresh_execution(plan)
+          changes = plan ? plan.changes : @operations.map(&:plan)
+          validate_operation_set!(changes)
+          { source_id: nil, changes: changes, completed: [] }
+        end
+
+        def validate_operation_set!(changes)
+          operation_resources = @operations.map(&:resource)
+          change_resources = changes.map(&:resource)
+          return if operation_resources == change_resources
+
+          raise Errors::ConfigurationError.new(
+            "the saved plan does not match the configured operations",
+            hint: "Review the configuration and start a new `kit plan` and `kit apply`."
+          )
+        end
+
+        def execute(execution)
+          execution[:changes].each_with_index.map do |change, index|
+            if execution[:completed].include?(change.resource)
+              emit("operation_skipped", resource: change.resource, summary: change.summary,
+                                        reason: "already_completed")
+              next
+            end
+
+            execute_change(operation_for(change), change, index: index + 1, total: execution[:changes].length)
+          end
+        end
+
+        def execute_change(operation, change, index:, total:)
+          @cancellation.check!
+          started_at = monotonic_time
+          @journal.record_step(change.resource, "running")
+          emit("operation_started", resource: change.resource, summary: change.summary, action: change.action,
+                                    index: index, total: total)
+          emit("operation_progressed", resource: change.resource, summary: change.summary, action: change.action,
+                                       percent: 0)
+          operation.apply(change).tap do
+            @journal.record_step(change.resource, "success")
+            @last_confirmed = change.resource
+            emit("operation_progressed", resource: change.resource, summary: change.summary, action: change.action,
+                                         percent: 100)
+            emit_success(change, started_at)
+          end
+        rescue StandardError => e
+          @journal.record_step(change.resource, "failure", error: error_code(e))
+          emit_failure(change, e)
+          raise
+        end
+
+        def operation_for(change) = @operations.find { |operation| operation.resource == change.resource }
+
+        def emit_success(change, started_at)
+          emit("operation_succeeded", resource: change.resource, summary: change.summary, action: change.action,
+                                      duration_ms: elapsed_ms(started_at))
+        end
+
+        def emit_failure(change, error)
+          emit("operation_failed", resource: change.resource, summary: change.summary,
+                                   message: error.message, code: error_code(error))
+        end
+
+        def finish(status, started_at, error: nil)
+          @journal.finish(status, error: error)
+          emit("run_finished", status: status, duration_ms: elapsed_ms(started_at))
+        end
+
+        def error_code(error) = error.respond_to?(:code) ? error.code : "unexpected_error"
+        def failure_status(error) = error.is_a?(Cancellation::Cancelled) ? "cancelled" : "failure"
+
+        def emit_recovery_guidance
+          confirmed = @last_confirmed ? " Last confirmed step: #{@last_confirmed}." : " No step was confirmed."
+          emit(
+            "warning_emitted",
+            message: "Run #{run_id} is incomplete.#{confirmed} Correct the cause, then run `kit resume #{run_id}`."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "../clock"
+require_relative "../events"
+
+module Kitsune
+  module Kit
+    module Workflows
+      class Base
+        def initialize(config:, event_bus: Events::NullBus.new, clock: Clock.new)
+          @config = config
+          @event_bus = event_bus
+          @clock = clock
+          @run_id = SecureRandom.uuid
+        end
+
+        private
+
+        attr_reader :config, :event_bus, :run_id, :clock
+
+        def emit(type, **data)
+          event_bus.publish(Events::Event.build(type, run_id: run_id, time: clock.now, **data))
+        end
+
+        def monotonic_time = clock.monotonic
+        def elapsed_ms(started_at) = ((monotonic_time - started_at) * 1000).round
+      end
+    end
+  end
+end