kitsune-kit 0.4.0 → 0.5.0

data/docs/testing.md

@@ -0,0 +1,200 @@
+# Testing and quality gates
+
+Kitsune Kit uses layers because no single test environment accurately represents provider APIs, SSH, systemd, UFW, Docker and public network exposure.
+
+## Local commands
+
+```bash
+bin/setup                         # install gems and run the local gate
+bundle exec rake test             # complete normal RSpec suite + coverage gate
+bundle exec rake lint             # RuboCop + ShellCheck
+bundle exec rake security         # Bundler Audit
+bundle exec rake build            # build the gem
+bundle exec rake artifact_smoke   # install the gem with fresh dependencies and verify its CLI
+bundle exec rake ci               # lint, tests and gem build
+bundle exec rake integration      # Docker-backed SSH/script suite
+```
+
+Run an individual spec without applying whole-suite coverage thresholds:
+
+```bash
+bundle exec rspec spec/unit/configuration_spec.rb
+```
+
+Set `KITSUNE_COVERAGE_GATE=1` to force the full threshold for a custom selection or `0` for diagnostic subsets. CI always runs the complete gate.
+
+## Test layers
+
+### Unit/domain
+
+Fast tests cover configuration precedence/validation, plans, errors/exit codes, redaction, reporters, state locking/writes, run journals, operation idempotence, rollback calculations, workflow resume/failure and TUI state/rendering. No network is used.
+
+### Fakes and contracts
+
+`FakeProvider`, `FakeTransport`, `FakeStateStore` and `FakeReporter` are deterministic memory adapters with
+recorded calls or captured events. Shared examples define provider, transport and state-store behavior. Real
+adapters execute those same contracts against simulated SDK/SSH boundaries, including timeouts, exact IDs,
+status channels and hostile arguments.
+
+### CLI process tests
+
+The executable runs as a subprocess to verify global/help/version behavior, invalid syntax, exit codes, JSON parsing, non-TTY behavior and environment selection. Core behavior is separately tested through workflows so subprocess coverage is not mistaken for domain coverage.
+
+### Shell scripts
+
+Every remote script passes ShellCheck and `bash -n`. CI mounts scripts read-only into both supported Ubuntu images to ensure the distributed Bash parses there.
+
+A simple container does not prove systemd/UFW behavior. The project does not claim otherwise; those effects are checked on a VPS in the E2E layer.
+
+### Ephemeral SSH integration
+
+`rake integration` builds an Ubuntu OpenSSH container with a temporary Ed25519 key. It verifies real public-key authentication, stdout/stderr/status separation, safe quoting, exact-byte upload/mode, host-key rejection, authentication failure and command timeout. It also uses a pseudo-terminal to prove that the TUI restores the main screen and console mode after normal exit and `SIGINT`. CI runs it on Ubuntu 22.04 and 24.04 base images.
+
+Docker must be installed and running. If unavailable, examples report why they were skipped locally; the CI integration job first requires `docker info`, so it cannot silently pass without Docker.
+
+### DigitalOcean E2E
+
+The E2E suite is billable and never runs from a normal test command. Required variables:
+
+```text
+KITSUNE_E2E=1
+DO_API_TOKEN
+KITSUNE_E2E_SSH_KEY_ID
+KITSUNE_E2E_KEY_PATH
+POSTGRES_PASSWORD (generated by the test workflow)
+REDIS_PASSWORD (generated by the test workflow)
+```
+
+Use a dedicated DigitalOcean token and SSH key pair for this suite. The private key must not have a passphrase
+because the GitHub runner cannot answer an unlock prompt. Generate a test-only Ed25519 pair locally:
+
+```bash
+ssh-keygen -t ed25519 -f ~/.ssh/kitsune_e2e_ed25519 -C kitsune-e2e -N ""
+chmod 0600 ~/.ssh/kitsune_e2e_ed25519
+```
+
+Upload only `~/.ssh/kitsune_e2e_ed25519.pub` in DigitalOcean under **Settings → Security → SSH keys → Add SSH
+Key**. Never upload or paste the private file into DigitalOcean. `KITSUNE_E2E_SSH_KEY_ID` is the numeric ID
+assigned to that uploaded public key, not its fingerprint or path. With `DO_API_TOKEN` already exported, list
+the available IDs without printing the token:
+
+```bash
+curl --fail --silent --show-error \
+  -H "Authorization: Bearer ${DO_API_TOKEN}" \
+  https://api.digitalocean.com/v2/account/keys |
+  ruby -rjson -e 'JSON.parse(STDIN.read).fetch("ssh_keys").each { |key| puts [key["id"], key["name"], key["fingerprint"]].join("\t") }'
+```
+
+The minimum custom token scopes used by this suite are `account:read`, `droplet:read`, `droplet:create`,
+`droplet:delete`, `regions:read`, `sizes:read`, `actions:read`, `image:read`, `ssh_key:read`, `tag:read` and
+`tag:create`. The dynamic expiry tag makes `tag:create` necessary. DNS scopes are not required by the current
+E2E configuration. DigitalOcean does not allow changing an existing token's scopes; create a replacement token
+if any permission is missing.
+
+Before authorizing a billable run, confirm that the token can access the endpoint used by `doctor`:
+
+```bash
+curl --output /dev/null --silent --show-error --write-out '%{http_code}\n' \
+  -H "Authorization: Bearer ${DO_API_TOKEN}" \
+  https://api.digitalocean.com/v2/account
+```
+
+The expected status is `200`; `403` means the token lacks `account:read` or the selected team role does not grant
+it.
+
+For a local run, keep the token out of shell history and export the remaining values:
+
+```bash
+printf 'DigitalOcean token: '
+IFS= read -r -s DO_API_TOKEN
+printf '\n'
+export DO_API_TOKEN
+export KITSUNE_E2E_SSH_KEY_ID="12345678"
+export KITSUNE_E2E_KEY_PATH="$HOME/.ssh/kitsune_e2e_ed25519"
+export KITSUNE_E2E=1
+bundle exec rake e2e
+```
+
+The optional `KITSUNE_E2E_REGION` and `KITSUNE_E2E_SIZE` variables override the defaults `sfo3` and
+`s-1vcpu-1gb` when that combination is unavailable.
+
+For GitHub Actions, add these repository secrets under **Settings → Secrets and variables → Actions**:
+
+| GitHub secret | Value |
+| --- | --- |
+| `DO_API_TOKEN` | Dedicated DigitalOcean token |
+| `KITSUNE_E2E_SSH_KEY_ID` | Numeric ID of the uploaded public key |
+| `KITSUNE_E2E_KEY` | Complete contents of the matching private key file |
+
+GitHub writes `KITSUNE_E2E_KEY` to a restricted temporary file and sets `KITSUNE_E2E_KEY_PATH` itself. After
+the workflow exists on GitHub, run **Actions → Real infrastructure → Run workflow**. It has no schedule and
+therefore cannot create billable infrastructure unless someone dispatches it explicitly.
+
+Run only in a dedicated account/project:
+
+```bash
+KITSUNE_E2E=1 bundle exec rake e2e
+```
+
+It creates a unique TTL-tagged Droplet, applies the complete configuration including PostgreSQL/Redis, runs CLI doctor/plan, demands a zero-change second plan, checks data ports from outside, rolls back and destroys in `ensure`.
+
+Before creating anything, the suite derives the public half of `KITSUNE_E2E_KEY_PATH` and compares it with the
+public key returned by DigitalOcean for `KITSUNE_E2E_SSH_KEY_ID`, then validates account API access. A key
+mismatch or missing `account:read` permission fails without creating a billable Droplet. After creation, Kitsune Kit
+waits up to two minutes for Ubuntu SSH readiness because an `active` API status and public IP do not guarantee
+that `sshd` has finished starting.
+
+The manually dispatched workflow serializes E2E runs and has a 45-minute limit. Its always-run cleanup job invokes
+`script/cleanup-ci-resources`, which is dry-run by default and only considers `kitsune-ci` Droplets with an expired
+`kitsune-expires-EPOCH` tag:
+
+```bash
+bundle exec ruby script/cleanup-ci-resources
+bundle exec ruby script/cleanup-ci-resources --execute
+```
+
+Unit tests inject a fake Droplet API into the cleanup class and prove that dry-run never deletes, untagged or
+unexpired resources are ignored, and `--execute` uses only the filtered provider IDs.
+
+## Coverage
+
+SimpleCov records line and branch coverage. The gate is raised with the new core and must not be improved by excluding difficult production files. Destructive paths require explicit examples even when another path happens to cover the same line.
+
+The complete suite enforces at least 80% line/50% branch coverage across all production code and 85% branch coverage in the domain core. For this gate, the core is `lib/kitsune/kit` excluding presentation (`cli.rb`, `tui/`, `reporters/`) and external adapters; operations/workflows/configuration/state remain included. `script/verify-core-coverage` calculates this directly from SimpleCov's current result.
+
+Coverage is evidence of exercised control flow, not proof of provider/system correctness; contract, integration, security and E2E tests remain mandatory.
+
+The dated manual source review, remediated findings and residual infrastructure risks are in
+[Security audit](security-audit.md).
+
+## CI jobs
+
+Pull requests run:
+
+- unit tests on every declared Ruby family;
+- CLI process tests;
+- adapter contracts;
+- Ruby/shell lint;
+- dependency audit;
+- gem build, isolated installation and executable smoke test;
+- Docker SSH/script integration for both supported Ubuntu releases.
+
+The credential-gated, manually dispatched workflow runs the DigitalOcean lifecycle and cleanup. Secrets are
+never available to untrusted pull-request jobs, and no calendar trigger creates billable infrastructure.
+
+The artifact job deliberately resolves runtime dependencies without the repository lockfile, runs from outside
+the checkout, verifies the exact public command set, and initializes a temporary project. This catches undeclared
+standard-library gems and framework commands that a locked development bundle could hide.
+
+## Writing a new operation test
+
+At minimum cover:
+
+1. absent resource plan/apply/verification;
+2. already-correct no-change behavior;
+3. allowed update and immutable/destructive drift;
+4. failure before and after mutation;
+5. resume after a persisted partial step;
+6. rollback of owned state and refusal to touch pre-existing state;
+7. timeout/cancellation;
+8. hostile input and secret redaction.

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