kitsune-kit 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc00c2d601950e0e2ab250c0b19bf8d46eb31fc37490494ab937114b00ebbbf4
-  data.tar.gz: 1939661240dba888530d041ffb0a36c39946674df556f236015ab8bc3885fd89
+  metadata.gz: 02a64110c8bffb9342d3cd0550360d95d871a4c1179f33899e34787abe59a080
+  data.tar.gz: 2bf327e34d000c12ba3883573a088493f353f5265ca2b7aa4693b645ba9f3ee9
 SHA512:
-  metadata.gz: e9051494678982c1c728d6c64b0a428ac6d313872d8af5c92ecfecc402fc206173deffbbd789f33f808783d9cfdc18b35ac1d5fe7d5aae581db79e289a74c993
-  data.tar.gz: 83003db9d7c0f50b206d6375f46244f2e582b770ad6b7c1515b9af39aaa74f63c505893341f37690259ef40835eb619261722747dbd485cca018a6619a9679d9
+  metadata.gz: 23e94dae8106856bd149f8e66d47ee61c47d1ddb5ccbb3311ec8f214d0874b4cdf64b40777d7f6dd04b393be684044785e6135f23f78618237ba5e6927e317cb
+  data.tar.gz: 59f168aa081fc7047a0e49a1107c288cdd4f2c04e0da45be46e514c89e181ee023e1f860ceb2511017e1f9885e9c2a773a6008959a9c3c78ff15e49bf75f8750

data/CHANGELOG.md

@@ -1,6 +1,121 @@
 # Changelog
 
+All notable changes are documented here. The project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and [Semantic Versioning](https://semver.org/); minor releases may change public interfaces before 1.0.
+
+## [Unreleased]
+
+## [0.5.0] - 2026-08-14
+
+### Added
+
+- Comprehensive security hardening and release process.
+- Architecture decisions for the direct rewrite, presentation parity, configuration, state and operation semantics.
+- Contribution and security policies.
+- Typed configuration, domain errors/results/events, versioned state, run journals and safe resume.
+- Provider and SSH contracts with deterministic fakes and hardened DigitalOcean/Net::SSH adapters.
+- Deterministic fake state/reporter adapters and shared real/fake state contracts.
+- Read-only `doctor` and `plan`, non-interactive/JSON output, stable exit codes and support bundles.
+- Ownership-aware server, DNS, Docker, PostgreSQL and Redis lifecycle operations.
+- Optional pure-Ruby full-screen TUI over the same workflows as the conventional CLI.
+- Unit, contract, hostile-input, CLI, headless TUI, Docker SSH integration and guarded DigitalOcean E2E suites.
+- Matrix CI, dependency audit, shell lint, artifact installation smoke test, Dependabot and TTL resource cleanup.
+- Complete user, security, provider, service, architecture, testing, troubleshooting and TUI documentation.
+- Exact-ID server state import, schema compatibility guidance and a documented manual security audit.
+- External PostgreSQL/Redis endpoint mode that never assumes or mutates a local Docker service.
+- Pseudo-terminal TUI lifecycle and restoration coverage.
+
+### Changed
+
+- Version 0.5.0 directly replaces the earlier preview CLI; legacy compatibility is not a goal.
+- Declare Ruby 3.2–3.4 support explicitly; Ruby 4 remains blocked by the current DigitalOcean SDK dependency chain.
+- The command tree is now `init -> doctor -> plan -> apply`, with explicit resource subcommands.
+- PostgreSQL and Redis are private and disabled by default; data destruction is separate from service removal.
+- SSH, firewall, Docker and metrics setup use versioned verified scripts and captured rollback state.
+- Safety-critical SSH/firewall transitions reuse a preserved session and transactionally recover failed changes.
+- Service data destruction offers an optional backup and requires exact interactive or automation confirmation.
+
+### Fixed
+
+- Declared `base64`, `bigdecimal` and transitive `ostruct` requirements explicitly for supported Ruby releases.
+- Made the ShellCheck availability probe portable across macOS and Ubuntu CI runners.
+- Prevented framework commands added by newer Thor releases from silently changing Kitsune Kit's public CLI.
+- Wait for SSH readiness after a new Droplet becomes active and reject mismatched E2E key pairs before billing.
+- Validate DigitalOcean account access before E2E provisioning and avoid false server drift warnings.
+- Use DropletKit's real `account.info` endpoint instead of a fake-only `account.get` method.
+- Correct TUI plan/doctor shortcut routing and prevent full-width terminal frames from scrolling during redraws.
+- Wait for authenticated SSH, rather than an open Docker proxy port, before running container integration cases.
+
+### Removed
+
+- Legacy bootstrap/setup command classes and interpolated Compose/env templates.
+- The unused RBS placeholder; types will only return with a maintained, CI-checked contract.
+
+### Security
+
+- Added strict SSH host-key verification, input allow-lists, safe argument transport and secret redaction.
+- Added exact provider/resource identity checks, atomic restricted state, protected Docker firewall rules and explicit destructive confirmations.
+- Prevented Redis passwords from resolving into container command arguments and made installer/config temporaries failure-safe.
+
+## [0.4.1] - 2025-06-01
+
+### Fixed
+
+- Corrected Redis defaults and removed an accidental debugger dependency from runtime code.
+
+## [0.4.0] - 2025-05-04
+
+### Added
+
+- DigitalOcean DNS record management.
+
+### Changed
+
+- Replaced the external color dependency with the internal ANSI helper.
+- Corrected generated development environment defaults.
+
+## [0.3.0] - 2025-05-03
+
+### Added
+
+- Redis service setup with Docker Compose.
+- Version command and initial CLI integration tests.
+
+### Fixed
+
+- Corrected SSH invocation and PostgreSQL setup behavior.
+
+## [0.2.1] - 2025-05-01
+
+### Changed
+
+- Expanded documentation for swap and DigitalOcean metrics support.
+
+## [0.2.0] - 2025-05-01
+
+### Added
+
+- Managed swap setup and rollback.
+- DigitalOcean metrics-agent setup.
+
+## [0.1.1] - 2025-05-01
+
+### Added
+
+- PostgreSQL firewall integration and improved CLI feedback.
+
 ## [0.1.0] - 2025-04-29
+
 ### Added
-- First public release
-- Bootstrap commands for DigitalOcean + Docker + PostgreSQL
+
+- First public preview.
+- Bootstrap commands for DigitalOcean, Docker and PostgreSQL.
+
+[Unreleased]: https://github.com/omarhrra/kitsune-kit/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/omarhrra/kitsune-kit/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/omarhrra/kitsune-kit/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/omarhrra/kitsune-kit/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/omarhrra/kitsune-kit/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/omarhrra/kitsune-kit/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/omarhrra/kitsune-kit/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/omarhrra/kitsune-kit/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to Kitsune Kit
+
+Kitsune Kit is being rebuilt as a secure, inspectable infrastructure CLI. Read the architecture decisions in `docs/architecture/decisions` before changing public commands, configuration, state, events or destructive behavior.
+
+## Setup
+
+Requirements:
+
+- Ruby 3.2 or newer
+- Bundler 4.0.18
+- ShellCheck for remote script linting
+- Docker for integration tests
+
+Run:
+
+```bash
+bin/setup
+bundle exec rake ci
+```
+
+## Development commands
+
+```bash
+bundle exec rake spec       # Ruby tests
+bundle exec rake lint       # Ruby and shell lint
+bundle exec rake security   # dependency 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         # local pull-request gate
+```
+
+Integration and real-provider tests are kept separate because they require Docker or credentials:
+
+```bash
+bundle exec rake integration
+KITSUNE_E2E=1 bundle exec rake e2e
+```
+
+## Adding an operation
+
+An operation must validate input, calculate a non-mutating plan, be idempotent, verify its result, declare destructive effects, redact secrets, use timeouts and have success/no-change/failure tests. Provider and SSH code belongs in adapters, not workflows or presentation classes.
+
+Every action exposed in the TUI must have a CLI equivalent. Domain behavior is tested below either presentation layer.
+
+## Adding or changing a provider
+
+Implement the provider port without leaking SDK values or exceptions into the core. The adapter must:
+
+- use exact provider IDs for destructive calls;
+- preserve configured ownership tags;
+- map authentication, retryable provider and timeout failures to domain errors;
+- persist an ID before waiting on a newly created resource;
+- satisfy the shared provider contract and adapter-specific HTTP/SDK tests;
+- document credentials, permissions, identity and cleanup behavior.
+
+Do not add a second provider until its full create/wait/resume/delete lifecycle can run through existing workflows without provider conditionals in presentation code.
+
+## Tests
+
+Every behavior change needs the smallest appropriate unit/contract tests plus integration coverage when it crosses a real process, SSH or shell boundary. Destructive paths, failure-after-mutation, retry/resume, timeout and hostile inputs require explicit examples.
+
+Run the complete local gate before opening a pull request:
+
+```bash
+bundle exec rake ci
+bundle exec rake integration # when Docker/SSH/scripts changed
+```
+
+The DigitalOcean E2E suite is billable and credential-gated. Never run it against a production account; follow `docs/testing.md`.
+
+## Pull requests
+
+- Keep changes focused on one coherent capability.
+- Include tests and documentation with behavior changes.
+- Never commit tokens, private keys, `.kitsune/state`, logs or generated support bundles.
+- Explain destructive behavior and rollback semantics explicitly.
+- Update `CHANGELOG.md` under `Unreleased` for user-visible changes.
+
+Commit messages should be imperative and describe one coherent change. Pull requests should explain user-visible behavior, security/destruction implications, test evidence and any migration. A maintainer may squash on merge.
+
+## Releases
+
+Releases follow `docs/releasing.md`. Do not publish manually with a long-lived RubyGems API key. The protected `release` environment and RubyGems trusted publisher must approve the tag-triggered workflow.

data/README.md

@@ -1,198 +1,170 @@
-# Kitsune Kit 🦊
+# Kitsune Kit
 
-<p align="center">
-   <img src="kitsune-kit-logo.jpg" alt="Kitsune Logo" width="180"/>
-</p>
+Kitsune Kit prepares Ubuntu servers for Docker and Kamal deployments through a predictable, inspectable CLI.
 
-**Kitsune Kit** is a Ruby gem that automates the provisioning, configuration, and setup of remote Linux servers (VPS) to host applications deployed with [Kamal](https://github.com/basecamp/kamal) or Docker Compose. It is designed to work on DigitalOcean infrastructure (for now), featuring reversible commands and a clear workflow.
+> Status: `0.5.0` (pre-1.0). DigitalOcean and Ubuntu 22.04/24.04 LTS are supported. The command, configuration and state schemas may still change before 1.0.
 
-> 🛠️ *Ideal for Ruby developers who want to launch production without relying on other services.*
+## What it does
 
----
+- Provisions an explicitly tagged DigitalOcean Droplet.
+- Configures a deploy user, verified SSH policy, UFW, swap and unattended security updates.
+- Installs Docker Engine and Docker Compose from Docker's official Ubuntu repository.
+- Optionally installs private PostgreSQL/Redis services or represents provider-managed external endpoints.
+- Creates exact DNS records without adopting unrelated resources.
+- Shows a plan before changing infrastructure and records managed state for resume and rollback.
+- Offers both a conventional CLI and an optional full-screen TUI over the same workflows.
 
-## 🔍 Main Features
+Kitsune Kit is not a general-purpose configuration manager and does not manage arbitrary existing servers. It only removes resources recorded in its local state.
 
-- 🧪 **Automatically provisions** a Droplet on DigitalOcean
-- 👤 Configures a secure, passwordless `deploy` user
-- 🔐 Applies firewall rules (UFW) for SSH, HTTP, HTTPS
-- ♻️ Enables automatic security updates (unattended-upgrades)
-- 💾 Configures swap space for better performance
-- 📊 Installs [DigitalOcean monitoring agent](https://docs.digitalocean.com/products/monitoring/how-to/install-agent/)
-- 🌐 **Automatically links** domains or subdomains (A records) to your server using DigitalOcean DNS
-- 🐳 Installs and configures Docker Engine and private networking
-- 🐘 Deploys PostgreSQL via Docker Compose with healthcheck
-- 🗄️ Deploys Redis via Docker Compose with healthcheck
-- 🔄 All steps can be rolled back (`--rollback`)
-- ⚡ Fast, reproducible and without relying on YAML or complex external tools
+## Requirements
 
----
+- Ruby 3.2, 3.3 or 3.4 (`>= 3.2`, `< 4.0`). Ruby 4 support is currently blocked by the DigitalOcean SDK dependency chain.
+- A DigitalOcean account, API token and uploaded SSH public key.
+- A local private SSH key with restricted permissions.
+- A project directory whose `.kitsune/` state can be backed up securely.
 
-## 📦 Installation
-
-Add this line to your `Gemfile`:
-
-```ruby
-gem "kitsune-kit"
-```
-
-Or install it manually:
+## Installation
 
 ```bash
 gem install kitsune-kit
 ```
 
----
-
-## ⚙️ Prerequisites
-
-1. Configure a DigitalOcean API token:
-    ```bash
-    export DO_API_TOKEN="your_token"
-    ```
-
-2. Have the SSH key ID uploaded to DigitalOcean:
-    ```bash
-    export SSH_KEY_ID="123456"
-    ```
-
-3. Have the private key installed on your local machine:
-    ```bash
-    export SSH_KEY_PATH="~/.ssh/id_rsa"
-    ```
+Or add it to a project:
 
----
-
-## 🚀 Getting Started
+```ruby
+gem "kitsune-kit", "~> 0.5.0"
+```
 
-Initialize the Kitsune project structure:
+## Safe quick start
 
 ```bash
 kit init
-```
 
-This will create the `.kitsune/` directory, multiple `.env` files, and the necessary Docker templates. Run it in your project's root directory.
+# Edit .kitsune/config.yml first.
+export DO_API_TOKEN="..."
 
----
-
-## 🔧 Main Commands
-
-### 🏗️ Server Provisioning
-
-```bash
-kit bootstrap execute
+kit doctor
+kit plan
+kit apply
 ```
 
-This creates a Droplet and executes:
+`kit apply` asks for confirmation. In automation, review the plan and use `kit apply --no-input --yes`. The first SSH connection also requires verifying the displayed host-key fingerprint; non-interactive runs must pass the exact value with `--trust-host-key`.
 
-1. `setup_user create`
-2. `setup_firewall create`
-3. `setup_unattended create`
-4. `setup_swap`
-5. `setup_do_metrics`
+The recommended workflow is always:
 
-### 🐳 Full Docker Installation
-
-```bash
-kit bootstrap_docker execute --server-ip 123.123.123.123
+```text
+init -> edit configuration -> doctor -> plan -> apply -> doctor
 ```
 
-This applies in order:
+See [Getting started](docs/getting-started.md) for the complete first-run procedure.
 
-1. `setup_docker_prereqs create`
-2. `install_docker_engine create`
-3. `postinstall_docker create`
+## Commands
 
-### 🐘 Install PostgreSQL with Docker Compose
+| Command | Purpose | Changes resources |
+| --- | --- | --- |
+| `kit init` | Create project configuration | Local |
+| `kit doctor` | Check configuration, credentials, connectivity and drift | No |
+| `kit plan` | Show the desired changes | No |
+| `kit apply` | Apply the reviewed plan | Yes |
+| `kit resume [RUN_ID]` | Continue an incomplete run | Yes |
+| `kit status` | Show tracked state and the server | No |
+| `kit server import` | Recover a verified server ID after state loss | Exact name |
+| `kit rollback` | Restore managed configuration; preserve server and service data | Yes |
+| `kit server ACTION` | Show, create, configure, connect to or destroy the server | Depends |
+| `kit service TYPE ACTION` | Manage PostgreSQL or Redis | Depends |
+| `kit dns ACTION` | List, plan, apply or remove configured records | Depends |
+| `kit docker ACTION` | Inspect, install or uninstall Docker | Depends |
+| `kit env ACTION [NAME]` | List, read or select environments | Local |
+| `kit support bundle` | Create a local redacted diagnostic file | Local |
+| `kit ui` | Open the optional interactive terminal interface | Depends |
 
-```bash
-kit setup_postgres_docker create --server-ip 123.123.123.123
-```
+Run `kit help` or `kit help COMMAND` for built-in help. The complete action and option reference is in [Commands](docs/commands.md).
 
-It will provide you with a `DATABASE_URL` ready for Rails or any other app.
+## Configuration and environments
 
----
+The base configuration is `.kitsune/config.yml`. Environment overlays live at `.kitsune/environments/NAME.yml`. Selection precedence is:
 
-## ♻️ Rollback for Each Step
+1. `--env NAME`
+2. `KITSUNE_ENV`
+3. `.kitsune/environment`
+4. `development`
 
-Each command accepts the `--rollback` flag. For example:
+Within a selected environment, value precedence is defaults, base file, environment overlay, supported environment-variable overrides, then explicit internal API overrides. Tokens and service passwords are read from environment variables and are never stored in configuration or state.
 
-```bash
-kit bootstrap execute --rollback --keep-server
-```
-
-This:
-- Reverts the server configuration (`unattended`, `firewall`, `user`)
-- Optionally **deletes the Droplet** (if you don't use `--keep-server`)
+See [Configuration](docs/configuration.md).
 
-The same applies to any other subcommand, such as:
+## Security model
 
-```bash
-kit bootstrap_docker execute --rollback --server-ip ...
-kit setup_postgres_docker rollback --server-ip ...
-```
+- PostgreSQL and Redis have no published host port by default.
+- Publishing a data port requires explicit allowed CIDRs; Kitsune Kit also manages matching `DOCKER-USER` firewall rules.
+- SSH host keys use trust-on-explicit-confirmation and are subsequently checked strictly.
+- Shell arguments are validated and passed separately; uploaded scripts and configuration use restricted modes.
+- State writes are locked and atomic, with a recoverable backup.
+- Logs and support bundles are redacted and never uploaded automatically.
+- Destructive commands require exact or explicit confirmation.
 
----
+Read [Security](docs/security.md) before managing production infrastructure.
 
-## 🌎 Support for Multiple Environments
+## PostgreSQL and Redis
 
-Use `switch_env` to change between environments:
+Services are optional and disabled initially. Enable a service in configuration and export its configured secret:
 
 ```bash
-kit switch_env to production
+export POSTGRES_PASSWORD="$(ruby -rsecurerandom -e 'print SecureRandom.base64(36)')"
+kit service postgres install
 ```
 
-This updates `.kitsune/kit.env` and creates (if it doesn't exist) `.kitsune/infra.production.env`.
+`remove` stops/removes containers but preserves the Docker volume. `destroy-data` permanently removes it and requires `--confirm-destroy TYPE@ENV`. Create a backup first.
 
----
+See [PostgreSQL](docs/services/postgres.md) and [Redis](docs/services/redis.md).
 
-## 🔗 Integration with Kamal
+## CLI and optional TUI
 
-Once the server is configured:
+Kitsune Kit is fully usable without the TUI. Every infrastructure action available in the full-screen interface invokes the same domain workflow and has a conventional command equivalent. Scripts and CI should use subcommands, `--no-input`, and optionally `--format json`.
 
-1. Define your `kamal.yml` pointing to the created droplet
-2. Run `kamal setup` to initialize the deployment
-3. Use `kamal deploy` as usual
+With no arguments, `kit` opens the TUI only when both standard input and output are terminals; otherwise it prints help. Use `kit ui` to request it explicitly. See [TUI](docs/tui.md).
 
----
-
-## 💡 Tips
-
-- Use `kit init` in every new project.
-- Customize `.kitsune/docker/postgres.yml` if you need additional services.
-
----
-
-## 📘 Quick Example
+## Automation and JSON
 
 ```bash
-# Initialize project structure
-kit init
+kit plan --format json --no-input --no-color
+kit apply --format json --no-input --yes
+```
 
-# Provision Droplet and configure everything
-kit bootstrap execute
+JSON documents include `schema_version`, command/run metadata, status, result, warnings and domain events. Errors are emitted as a versioned JSON object on standard error and have documented exit codes. Do not parse human output.
 
-# Install Docker
-kit bootstrap_docker execute --server-ip 123.123.123.123
+## Development
 
-# Set up the database
-kit setup_postgres_docker create --server-ip 123.123.123.123
+```bash
+bin/setup
+bundle exec rake test
+bundle exec rake lint
+bundle exec rake security
+bundle exec rake integration
+bundle exec rake ci
 ```
 
----
-
-## 🧪 In Development
+Docker-backed integration tests and credential-gated DigitalOcean E2E tests are intentionally separate. See [Testing](docs/testing.md) and [Contributing](CONTRIBUTING.md).
 
-- [ ] Support for other providers (Hetzner)
-- [ ] Create databases on another server
+## Documentation
 
----
+- [Getting started](docs/getting-started.md)
+- [Configuration](docs/configuration.md)
+- [Command reference](docs/commands.md)
+- [Security](docs/security.md)
+- [Manual security audit](docs/security-audit.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Architecture](docs/architecture.md)
+- [Testing](docs/testing.md)
+- [Releasing](docs/releasing.md)
+- [Roadmap and extension decisions](docs/roadmap.md)
 
-## 🔐 Security
+## Roadmap and stability
 
-Never upload your `.env` files to public repositories. Kitsune does not encrypt them: it assumes you control your machine and your repo. Add `.kitsune/` to your project's `.gitignore`.
+The current focus is stabilizing the DigitalOcean lifecycle, schema migrations and real-infrastructure E2E coverage before 1.0. Additional providers and extension hooks will be considered only after those contracts are stable.
 
----
+Security reports follow [SECURITY.md](SECURITY.md). Changes are recorded in [CHANGELOG.md](CHANGELOG.md).
 
-## 📄 License
+## License
 
-MIT License © [Omar Herrera / OmarHrra]
+Kitsune Kit is available under the [MIT License](LICENSE.txt).

data/SECURITY.md

@@ -0,0 +1,25 @@
+# Security policy
+
+## Supported versions
+
+Kitsune Kit is pre-1.0 software. Security fixes are provided for the latest release. Minor releases may change commands, configuration and state schemas until 1.0, so infrastructure state must be backed up before upgrading.
+
+## Reporting a vulnerability
+
+Do not open a public issue for vulnerabilities that could expose credentials, execute injected commands, destroy infrastructure or lock users out of servers. Report them privately to `contact@omarherrera.me` with:
+
+- affected version or commit;
+- reproduction steps;
+- impact;
+- suggested remediation, if known.
+
+Do not include real tokens, keys, domains or server addresses. An acknowledgement should be expected within seven days.
+
+## Security guarantees under development
+
+- Databases are private by default.
+- Secrets are never written to state or normal logs.
+- SSH host keys are verified.
+- Destructive operations require explicit confirmation.
+- Rollback only changes resources recorded as managed by Kitsune Kit.
+- User input is validated before reaching shell commands.

data/bin/kit

@@ -1,7 +1,10 @@
 #!/usr/bin/env ruby
-require "bundler/setup"
+
+# frozen_string_literal: true
+
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "kitsune/kit"
 require "kitsune/kit/cli"
 
+ARGV << ($stdin.tty? && $stdout.tty? ? "ui" : "help") if ARGV.empty?
 Kitsune::Kit::CLI.start(ARGV)

data/docs/architecture/decisions/0001-product-boundary.md

@@ -0,0 +1,23 @@
+# ADR 0001: Product boundary and rewrite policy
+
+- Status: accepted
+- Date: 2026-08-14
+
+## Context
+
+The published preview has no known users or dependent projects. Its commands mix presentation, provider calls, SSH, shell scripts and state mutation. Preserving those interfaces would make unsafe behavior part of the new design.
+
+## Decision
+
+Kitsune Kit will manage the complete lifecycle of a small Ubuntu application server on DigitalOcean: provisioning, SSH policy, firewall, updates, swap, Docker, optional private PostgreSQL and Redis services, and DNS.
+
+The existing CLI and configuration are not compatibility constraints. The new implementation replaces them directly. Git history is the archive for old behavior; production code will not contain legacy adapters or deprecated command aliases.
+
+The rewrite may be released as 0.5.0 after its real-provider end-to-end suite passes reliably.
+
+## Consequences
+
+- Breaking changes are expected before 1.0.
+- Documentation describes only the new interface.
+- Each old implementation is deleted when its replacement is verified.
+- Scope remains DigitalOcean and Ubuntu 22.04/24.04 until the first provider is stable.

data/docs/architecture/decisions/0002-core-and-interfaces.md

@@ -0,0 +1,23 @@
+# ADR 0002: One core with CLI, JSON and TUI presentations
+
+- Status: accepted
+- Date: 2026-08-14
+
+## Context
+
+Kitsune Kit must be pleasant interactively and fully usable in scripts and CI. A full-screen TUI is valuable for inspecting resources and following long operations, but cannot become a second infrastructure implementation.
+
+## Decision
+
+Application workflows depend only on ports for provider, transport, state, secrets, clock and event publishing. They never call Thor, `puts`, terminal widgets or concrete adapters.
+
+Workflows publish typed events. Human CLI output, JSON output, logs and the TUI consume the same event stream. Every TUI action has a documented CLI equivalent. The complete lifecycle works without installing or opening the TUI.
+
+The first TUI renderer will be isolated behind a presentation interface. A native rendering dependency may be adopted later without changing workflows.
+
+## Consequences
+
+- CLI and TUI parity is testable at the workflow-result level.
+- CI can use `--format json` and `--no-input`.
+- TUI failures cannot change domain semantics.
+- Presentation differences are limited to navigation, prompts and progress rendering.

data/docs/architecture/decisions/0003-configuration-state-and-secrets.md

@@ -0,0 +1,23 @@
+# ADR 0003: Configuration, state and secrets
+
+- Status: accepted
+- Date: 2026-08-14
+
+## Decision
+
+- `.kitsune/config.yml` contains versioned, non-secret project configuration.
+- `.kitsune/environments/<name>.yml` contains versioned environment overrides.
+- `.kitsune/state/<name>.json` contains versioned, non-secret managed-resource state.
+- Secrets come from environment variables initially. Secret-store adapters may be added later.
+- Configuration precedence is CLI, environment variables, the selected environment file, project file, safe defaults.
+- The active environment is selected by `--env`, then `KITSUNE_ENV`, then `.kitsune/environment`, then `development`.
+- State writes are locked and atomic.
+- State stores provider IDs and previous managed values; deletion never relies only on a resource name.
+- Reporters pass all values through one secret filter.
+- Version 1 is the new product baseline; legacy preview formats are not migrated or interpreted.
+- Any future schema transition must be an explicit, tested adjacent-version migration that preserves a backup.
+- Unknown/future configuration and state versions fail with compatible-version or migration guidance.
+
+## Consequences
+
+Existing `.env` infrastructure files are not read by the new product. Sensitive data is never persisted in state or diagnostic bundles.

data/docs/architecture/decisions/0004-supported-platforms.md

@@ -0,0 +1,19 @@
+# ADR 0004: Supported platforms
+
+- Status: accepted
+- Date: 2026-08-14
+
+## Decision
+
+- Ruby 3.2, 3.3 and 3.4 are supported (`>= 3.2`, `< 4.0`).
+- CI tests every supported Ruby minor version.
+- Local clients support macOS and Linux.
+- Managed servers support Ubuntu 22.04 and 24.04 LTS.
+- Docker Compose v2 is required.
+- DigitalOcean is the only supported provider before 1.0.
+
+Ruby 3.2 is selected because the new core uses immutable `Data` value objects. Dependencies that require a newer patch or minor version must not be mandatory until the support declaration is updated and verified.
+
+Ruby 4 is excluded from the 0.5.0 contract because DropletKit 3.22 constrains `faraday-retry` to the 2.2 series,
+whose gem metadata requires Ruby `< 4`. Support can be enabled once that provider dependency accepts a
+Ruby-4-compatible `faraday-retry` release, or when the provider adapter no longer depends on that SDK.