kitsune-kit 0.4.1 → 0.6.0

data/docs/troubleshooting.md

@@ -0,0 +1,123 @@
+# Troubleshooting
+
+Start with read-only evidence:
+
+```bash
+kit doctor --debug
+kit status
+kit plan
+```
+
+Do not delete `.kitsune/state/` or provider resources just to retry. The state is what prevents duplicate creation and unsafe deletion.
+
+If the primary state file and `.backup` are both unavailable, recover only an independently verified server identity with:
+
+```bash
+kit server import \
+  --provider-id EXACT_NUMERIC_DROPLET_ID \
+  --confirm-import CONFIGURED_SERVER_NAME
+kit doctor
+```
+
+Import checks the complete configured identity and records no SSH, firewall, Docker, service or DNS ownership. `doctor` and `plan` must be reviewed afterward; do not assume pre-existing remote files belong to Kitsune Kit.
+
+## Configuration file not found
+
+Run from the project root or pass `--root PATH`. Initialize once with `kit init`. If using `--config`, it must point to the base YAML file; relative environment overlays still come from the selected project root.
+
+## Invalid configuration
+
+Kitsune Kit reports every validation finding together when possible. Common causes:
+
+- placeholder `server.ssh_key_id` was not replaced;
+- service enabled without its password environment variable;
+- unsupported Ubuntu image slug;
+- published service has no allowed CIDR;
+- YAML boolean was quoted or malformed;
+- metrics enabled without a verified lowercase SHA256;
+- environment or resource name contains spaces/metacharacters.
+
+Correct the source file/environment variable and rerun `doctor` and `plan`.
+
+## Provider authentication or API error
+
+Confirm the environment variable named by `provider.token_env` is exported in the same process. Check token expiration/scopes, account/project, quota and region/size availability. Use `--debug` for the safe error class/context; Kitsune Kit intentionally does not print raw provider responses that might include sensitive details.
+
+## Server creation timed out
+
+Run `kit status` before doing anything else. If state contains the provider ID, do not create another Droplet manually. Inspect that exact ID in DigitalOcean, resolve provider/network delays, then:
+
+```bash
+kit resume
+```
+
+## SSH host key is not trusted
+
+This is expected on first contact. Verify the displayed SHA256 fingerprint independently. Interactive mode can save it. For automation:
+
+```bash
+kit doctor --no-input --trust-host-key SHA256:verified-value
+```
+
+A changed key can indicate server replacement or interception. Compare provider ID/state and investigate; do not remove known-host state reflexively.
+
+## Neither deploy nor root can connect
+
+Use DigitalOcean's console/recovery access and verify:
+
+- the configured private key matches the uploaded key ID;
+- deploy user's `authorized_keys` and permissions;
+- configured SSH port and UFW rules;
+- `sshd -t` and service status;
+- your source IP remains in `ssh.allowed_cidrs`.
+
+Kitsune Kit validates the deploy connection before disabling bootstrap assumptions, but out-of-band changes can still remove access.
+
+## Remote command or verification failed
+
+The error identifies the resource and stable code. Inspect the redacted session log under `.kitsune/logs/`, repair the underlying condition and use `kit resume`. A failed operation is not marked successful; temporary uploads are cleaned best-effort.
+
+For Docker failures, inspect disk space, conflicting packages, apt repository reachability, daemon status and `docker compose version`. For services, inspect Compose health/logs and the configured image architecture.
+
+Kitsune Kit refuses to remove Ubuntu/community Docker packages (`docker.io`, legacy Compose, `podman-docker`, `containerd` or `runc`) automatically because doing so could disrupt an existing installation. Migrate/remove those packages deliberately, preserve any existing Docker data, then rerun the plan.
+
+## Plan always reports drift
+
+`doctor` compares remote fingerprints and local ownership. Common causes are manual edits to managed files, missing markers, environment mismatch or restored server data with stale local state. Preserve `.kitsune/state/ENV.json` and its `.backup`; compare exact provider IDs and fingerprints. Do not adopt/delete by name without a deliberate recovery procedure.
+
+## PostgreSQL or Redis is publicly reachable
+
+Treat this as urgent. Stop/remove the service or close the provider/network firewall, then inspect:
+
+```bash
+kit doctor
+kit service TYPE status
+```
+
+Ensure `publish: false`, or narrow `bind`/`allowed_cidrs`. Inspect Docker's `DOCKER-USER` chain as well as UFW because published Docker ports can bypass ordinary UFW forwarding rules.
+
+## Apply/resume asks for confirmation in CI
+
+Use both flags after reviewing the plan:
+
+```bash
+kit apply --no-input --yes --format json
+kit resume --no-input --yes --format json
+```
+
+Permanent destruction still needs `--confirm-destroy`; this cannot be bypassed by `--yes`.
+
+## TUI does not open
+
+The TUI requires interactive stdin and stdout. Redirected/piped sessions should use conventional commands. Explicit `kit ui` without a TTY returns a configuration error instead of emitting terminal escape sequences. Minimum display size is 70×18.
+
+## Create a support bundle
+
+```bash
+kit support bundle
+```
+
+Kitsune Kit writes the restricted JSON file and prints its redacted contents in human mode. Review that output before
+sharing it; the bundle is never uploaded automatically. With `--format json`, inspect the returned local path.
+
+Open the generated JSON and inspect it before sharing. It is permission-restricted and redacted, but Kitsune Kit never uploads it or asserts that arbitrary user content cannot contain sensitive business data.

data/docs/tui.md

@@ -0,0 +1,57 @@
+# Optional terminal interface
+
+The TUI is a full-screen convenience layer. It is not required to install or use Kitsune Kit, and it contains no provider, SSH or infrastructure logic.
+
+```text
+kit                    Open the TUI only when stdin/stdout are interactive
+kit ui                 Request the TUI explicitly
+kit plan               Conventional CLI, always available
+kit apply --no-input   Conventional non-interactive CLI
+```
+
+When no TTY is available, bare `kit` prints help and `kit ui` returns a stable configuration error without writing alternate-screen escape sequences.
+
+## Screens
+
+- Dashboard: environment, server/managed resources and recent operations.
+- Plan: exact domain plan used by `kit plan`/`kit apply`.
+- Doctor: checks and actionable hints.
+- Logs: bounded, redacted event feedback.
+- Help and confirmation modals.
+
+Minimum usable terminal size is 70 columns by 18 rows. Smaller terminals show a resize message rather than corrupting layout.
+
+## Keys
+
+| Key | Action | CLI equivalent |
+| --- | --- | --- |
+| `j`/`k`, arrows | Select resource | presentation only |
+| `Tab` | Cycle screens | presentation only |
+| `PgUp`/`PgDn` | Scroll logs | presentation only |
+| `p` | Build/show plan | `kit plan` |
+| `a` | Confirm and apply visible/fresh plan | `kit apply` |
+| `d` | Run diagnostics | `kit doctor` |
+| `r` | Confirm and resume latest run | `kit resume` |
+| `l` | Show event logs | local log/output |
+| `?` | Toggle help | `kit help` |
+| `q` | Quit (confirmation while busy) | process exit |
+| `Ctrl+C` | Request cooperative cancellation; quit when idle | `SIGINT` |
+
+Apply/resume run in a worker thread so redraw/input remain responsive. Cancellation is cooperative between operations; the current remote command is still bounded by its timeout. After cancellation, a new token is used for the next action.
+
+## Functional parity
+
+The TUI's action object calls `InspectEnvironment`, `BuildPlan`, `Doctor` and `ApplyPlan` directly—the same workflows as the CLI. It cannot expose an infrastructure capability that lacks a conventional command. Technical/rare commands may remain CLI-only.
+
+Automated tests assert that CLI/TUI-facing planning returns the same `Plan#to_h`. Differences are limited to navigation, confirmation and rendering.
+
+## Implementation and testing
+
+The initial backend is pure Ruby:
+
+- `Tui::Store` converts domain events into immutable view state;
+- `Tui::Renderer` turns state into a deterministic text buffer;
+- `Tui::Controller` maps keys/modals/workers to shared actions;
+- `Tui::Terminal` owns raw mode, alternate screen, resize and restoration.
+
+Terminal restoration runs in `ensure`, including exceptions and `Ctrl+C`. Headless tests use fake terminals/events and snapshots; no real interactive terminal is needed. A future RatatuiRuby renderer can replace terminal/rendering components without changing the core or making the TUI mandatory.

data/lib/kitsune/kit/adapters/confirming_host_key_verifier.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "net/ssh/verifiers/always"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class ConfirmingHostKeyVerifier < Net::SSH::Verifiers::Always
+        def initialize(&confirmation)
+          super()
+          @confirmation = confirmation || ->(**) { false }
+        end
+
+        def verify(arguments)
+          super
+        rescue Net::SSH::HostKeyUnknown => e
+          remember_if_confirmed(e, arguments)
+        end
+
+        def verify_signature(&)
+          super
+        rescue Net::SSH::HostKeyUnknown => e
+          remember_if_confirmed(e, e.data)
+        end
+
+        private
+
+        def remember_if_confirmed(error, arguments)
+          approved = @confirmation.call(
+            host: arguments.fetch(:session).host_keys.host,
+            fingerprint: arguments.fetch(:fingerprint),
+            key_type: arguments.fetch(:key).ssh_type
+          )
+          raise error unless approved
+
+          error.remember_host!
+          true
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/digitalocean_provider.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "droplet_kit"
+require_relative "../errors"
+require_relative "provider"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class DigitalOceanProvider < Provider
+        POLL_INTERVAL = 5
+
+        def initialize(token:, client: nil, sleeper: Kernel, maximum_timeout: nil)
+          super()
+          raise Errors::AuthenticationError, "DigitalOcean token is missing" if token.to_s.empty?
+          if maximum_timeout && maximum_timeout <= 0
+            raise Errors::ConfigurationError, "timeout must be greater than zero"
+          end
+
+          @client = client || build_client(token, maximum_timeout)
+          @sleeper = sleeper
+        end
+
+        def validate_credentials!
+          @client.account.info
+          true
+        rescue StandardError => e
+          raise_provider_error(
+            "DigitalOcean authentication failed",
+            e,
+            authentication: true,
+            hint: "Use a current token for the selected team and include the account:read scope."
+          )
+        end
+
+        def validate_server_spec!(spec:)
+          validate_region!(spec)
+          validate_size!(spec)
+          validate_image!(spec)
+          true
+        rescue Errors::ConfigurationError
+          raise
+        rescue StandardError => e
+          raise_provider_error("Unable to validate DigitalOcean server configuration", e)
+        end
+
+        def find_server(name:, tags: [])
+          tag = tags.first
+          droplets = tag ? @client.droplets.all(tag_name: tag) : @client.droplets.all
+          droplet = droplets.find do |candidate|
+            candidate.name == name && (tags - Array(candidate.tags)).empty?
+          end
+          droplet && server_record(droplet)
+        rescue StandardError => e
+          raise_provider_error("Unable to find DigitalOcean server #{name}", e)
+        end
+
+        def find_server_by_id(id:)
+          server_record(@client.droplets.find(id: id))
+        rescue StandardError => e
+          return nil if not_found?(e)
+
+          raise_provider_error("Unable to find DigitalOcean server #{id}", e)
+        end
+
+        def create_server(spec:)
+          droplet = DropletKit::Droplet.new(
+            name: spec.fetch(:name),
+            region: spec.fetch(:region),
+            size: spec.fetch(:size),
+            image: spec.fetch(:image),
+            ssh_keys: [spec.fetch(:ssh_key_id)],
+            tags: spec.fetch(:tags, [])
+          )
+          server_record(@client.droplets.create(droplet))
+        rescue StandardError => e
+          raise_provider_error("Unable to create DigitalOcean server #{spec[:name]}", e)
+        end
+
+        def wait_until_ready(id:, timeout: 180)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          loop do
+            droplet = @client.droplets.find(id: id)
+            record = server_record(droplet)
+            return record if record.status == "active" && record.public_ip
+            break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+            @sleeper.sleep(POLL_INTERVAL)
+          end
+          raise Errors::TimeoutError.new(
+            "DigitalOcean server #{id} did not become ready within #{timeout} seconds",
+            hint: "Inspect the Droplet in DigitalOcean before retrying."
+          )
+        rescue Errors::Error
+          raise
+        rescue StandardError => e
+          raise_provider_error("Unable to wait for DigitalOcean server #{id}", e)
+        end
+
+        def delete_server(id:)
+          @client.droplets.delete(id: id)
+          true
+        rescue StandardError => e
+          raise_provider_error("Unable to delete DigitalOcean server #{id}", e)
+        end
+
+        def find_dns_record(zone:, name:, type:)
+          record = @client.domain_records.all(for_domain: zone).find do |candidate|
+            candidate.name == name && candidate.type == type
+          end
+          record && dns_record(zone, record)
+        rescue StandardError => e
+          raise_provider_error("Unable to inspect DNS record #{name}.#{zone}", e)
+        end
+
+        def upsert_dns_record(record:)
+          value = DropletKit::DomainRecord.new(type: record.type, name: record.name, data: record.data, ttl: record.ttl)
+          saved = if record.id
+                    @client.domain_records.update(value, for_domain: record.zone, id: record.id)
+                  else
+                    @client.domain_records.create(value, for_domain: record.zone)
+                  end
+          dns_record(record.zone, saved)
+        rescue StandardError => e
+          raise_provider_error("Unable to update DNS record #{record.name}.#{record.zone}", e)
+        end
+
+        def delete_dns_record(id:, zone:)
+          @client.domain_records.delete(for_domain: zone, id: id)
+          true
+        rescue StandardError => e
+          raise_provider_error("Unable to delete DNS record #{id} from #{zone}", e)
+        end
+
+        private
+
+        def build_client(token, maximum_timeout)
+          return DropletKit::Client.new(access_token: token) unless maximum_timeout
+
+          DropletKit::Client.new(
+            access_token: token, open_timeout: maximum_timeout, timeout: maximum_timeout
+          )
+        end
+
+        def server_record(droplet)
+          ip = droplet.networks&.v4&.find { |network| network.type == "public" }&.ip_address
+          ServerRecord.new(
+            id: droplet.id.to_s,
+            name: droplet.name,
+            status: droplet.status,
+            public_ip: ip,
+            region: droplet.region.respond_to?(:slug) ? droplet.region.slug : droplet.region.to_s,
+            size: droplet.size_slug || droplet.size&.slug,
+            image: droplet.image.respond_to?(:slug) ? droplet.image.slug : droplet.image.to_s,
+            tags: droplet.tags || []
+          )
+        end
+
+        def dns_record(zone, record)
+          DnsRecord.new(
+            id: record.id.to_s,
+            zone: zone,
+            name: record.name,
+            type: record.type,
+            data: record.data,
+            ttl: record.ttl
+          )
+        end
+
+        def raise_provider_error(message, cause, authentication: false, hint: nil)
+          error_class = authentication ? Errors::AuthenticationError : Errors::ProviderError
+          raise error_class.new(
+            message,
+            hint: hint || "Check provider credentials, connectivity and resource limits, then retry.",
+            context: { cause: cause.class.name },
+            retryable: !authentication
+          )
+        end
+
+        def not_found?(error)
+          error.respond_to?(:response) && error.response.respond_to?(:status) && error.response.status.to_i == 404
+        end
+
+        def validate_region!(spec)
+          region = @client.regions.all.find { |candidate| candidate.slug == spec.fetch(:region) }
+          return if region&.available
+
+          raise unavailable("region", spec[:region], "Choose an available DigitalOcean region.")
+        end
+
+        def validate_size!(spec)
+          size = @client.sizes.all.find { |candidate| candidate.slug == spec.fetch(:size) }
+          return if size&.available && Array(size.regions).include?(spec[:region])
+
+          raise unavailable("size", spec[:size], "Choose a size available in region #{spec[:region]}.")
+        end
+
+        def validate_image!(spec)
+          image = @client.images.all(type: "distribution").find do |candidate|
+            candidate.slug == spec.fetch(:image)
+          end
+          return if image && (Array(image.regions).empty? || Array(image.regions).include?(spec[:region]))
+
+          raise unavailable("image", spec[:image], "Choose a supported image available in #{spec[:region]}.")
+        end
+
+        def unavailable(field, value, hint)
+          Errors::ConfigurationError.new(
+            "DigitalOcean #{field} is unavailable: #{value}",
+            hint: hint,
+            context: { field: field, value: value }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/fake_clock.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../clock"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class FakeClock < Clock
+        attr_reader :now, :monotonic, :sleeps
+
+        def initialize(now: Time.utc(2026, 1, 1), monotonic: 0.0)
+          super()
+          @now = now.utc
+          @monotonic = Float(monotonic)
+          @sleeps = []
+        end
+
+        def sleep(seconds)
+          seconds = Float(seconds)
+          @sleeps << seconds
+          advance(seconds)
+          seconds
+        end
+
+        def advance(seconds)
+          seconds = Float(seconds)
+          @now += seconds
+          @monotonic += seconds
+          self
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/fake_provider.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "provider"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class FakeProvider < Provider
+        attr_reader :calls, :servers, :dns_records
+
+        def initialize(servers: [], dns_records: [], failures: {})
+          super()
+          @servers = servers.dup
+          @dns_records = dns_records.dup
+          @failures = failures
+          @calls = []
+        end
+
+        def validate_credentials!
+          record(:validate_credentials)
+          fail_if_requested!(:validate_credentials)
+          true
+        end
+
+        def validate_server_spec!(spec:)
+          record(:validate_server_spec, spec: spec)
+          fail_if_requested!(:validate_server_spec)
+          true
+        end
+
+        def find_server(name:, tags: [])
+          record(:find_server, name: name, tags: tags)
+          fail_if_requested!(:find_server)
+          @servers.find { |server| server.name == name && (tags.empty? || (tags - server.tags).empty?) }
+        end
+
+        def find_server_by_id(id:)
+          record(:find_server_by_id, id: id)
+          fail_if_requested!(:find_server_by_id)
+          @servers.find { |server| server.id.to_s == id.to_s }
+        end
+
+        def create_server(spec:)
+          record(:create_server, spec: spec)
+          fail_if_requested!(:create_server)
+          server = ServerRecord.new(
+            id: SecureRandom.uuid,
+            name: spec.fetch(:name),
+            status: "new",
+            public_ip: nil,
+            region: spec.fetch(:region),
+            size: spec.fetch(:size),
+            image: spec.fetch(:image),
+            tags: spec.fetch(:tags, [])
+          )
+          @servers << server
+          server
+        end
+
+        def wait_until_ready(id:, timeout:)
+          record(:wait_until_ready, id: id, timeout: timeout)
+          fail_if_requested!(:wait_until_ready)
+          server = @servers.find { |candidate| candidate.id == id }
+          raise KeyError, "server not found: #{id}" unless server
+
+          ready = server.with(status: "active", public_ip: server.public_ip || "203.0.113.10")
+          @servers[@servers.index(server)] = ready
+          ready
+        end
+
+        def delete_server(id:)
+          record(:delete_server, id: id)
+          fail_if_requested!(:delete_server)
+          !!@servers.reject! { |server| server.id == id }
+        end
+
+        def find_dns_record(zone:, name:, type:)
+          record(:find_dns_record, zone: zone, name: name, type: type)
+          @dns_records.find { |record| record.zone == zone && record.name == name && record.type == type }
+        end
+
+        def upsert_dns_record(record:)
+          record(:upsert_dns_record, record: record)
+          existing = find_dns_record(zone: record.zone, name: record.name, type: record.type)
+          saved = record.with(id: existing&.id || SecureRandom.uuid)
+          existing ? @dns_records[@dns_records.index(existing)] = saved : @dns_records << saved
+          saved
+        end
+
+        def delete_dns_record(id:, zone:)
+          record(:delete_dns_record, id: id, zone: zone)
+          !!@dns_records.reject! { |record| record.id == id && record.zone == zone }
+        end
+
+        private
+
+        def record(name, **arguments) = @calls << [name, arguments]
+
+        def fail_if_requested!(name)
+          failure = @failures[name]
+          raise failure if failure
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/fake_reporter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../reporters/reporter"
+
+module Kitsune
+  module Kit
+    module Adapters
+      # Deterministic event sink for exercising complete workflows without a terminal.
+      class FakeReporter < Reporters::Reporter
+        def initialize
+          super
+          @events = []
+          @mutex = Mutex.new
+        end
+
+        def handle(event)
+          @mutex.synchronize { @events << event }
+          event
+        end
+
+        def events = @mutex.synchronize { @events.dup }
+
+        def events_of(type)
+          @mutex.synchronize { @events.select { |event| event.type == type.to_s } }
+        end
+
+        def clear
+          @mutex.synchronize { @events.clear }
+          self
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/fake_secret_store.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../secret_stores/store"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class FakeSecretStore < SecretStores::Store
+        attr_reader :fetches
+
+        def initialize(values = {})
+          super()
+          @values = values.transform_keys(&:to_s)
+          @fetches = []
+        end
+
+        def fetch(name, required: true)
+          key = name.to_s
+          @fetches << key
+          value = @values.fetch(key, "")
+          if required && value.empty?
+            raise Errors::ConfigurationError.new(
+              "required secret #{key} is not set", hint: "Provide #{key} through the configured secret store."
+            )
+          end
+          value
+        end
+
+        def configured?(name) = !@values.fetch(name.to_s, "").empty?
+        def set(name, value) = @values[name.to_s] = value.to_s
+      end
+    end
+  end
+end