kitsune-kit 0.4.1 → 0.6.0

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.

data/docs/architecture/decisions/0005-operation-semantics.md

@@ -0,0 +1,19 @@
+# ADR 0005: Plan, apply, rollback, remove and destroy semantics
+
+- Status: accepted
+- Date: 2026-08-14
+
+## Decision
+
+- `plan` observes and describes changes without mutation.
+- `apply` converges actual state to desired state and verifies postconditions.
+- `rollback` restores captured prior state when restoration is safe and supported.
+- `remove` stops and removes a managed capability while preserving data.
+- `destroy` permanently removes a provider resource.
+- `destroy-data` permanently removes service data and is always separately confirmed.
+
+Destructive operations show exact IDs and require the resource name as confirmation in an interactive terminal or an explicit confirmation option in non-interactive mode.
+
+## Consequences
+
+The word rollback is never used as a synonym for deleting a server or Docker volume. Operations that cannot restore prior state say so before execution.

data/docs/architecture/decisions/0006-tui-backend.md

@@ -0,0 +1,21 @@
+# ADR 0006: Optional TUI backend
+
+- Status: accepted
+- Date: 2026-08-14
+
+## Context
+
+Kitsune Kit needs a full-screen terminal interface without making it necessary for automation or conventional CLI use. RatatuiRuby 1.5 provides excellent widgets and headless testing, but currently requires Ruby 3.2.9 or newer, distributes native platform artifacts, and is LGPL-3.0-or-later. Kitsune Kit currently supports the Ruby 3.2 series and must remain installable as one portable Ruby gem.
+
+## Decision
+
+- The domain emits presentation-neutral events.
+- `Tui::Store`, `Tui::Renderer`, `Tui::Controller` and `Tui::Terminal` are separate components.
+- The initial renderer uses a small ANSI terminal backend and a deterministic text buffer.
+- Every TUI action invokes the same workflow used by the conventional CLI.
+- A future RatatuiRuby backend may replace only renderer, input and terminal lifecycle components.
+- The TUI remains optional at runtime; non-TTY use never initializes it.
+
+## Consequences
+
+The gem has no native TUI dependency and works completely through CLI/JSON. The initial widget set is intentionally smaller than RatatuiRuby, but its state, navigation, worker and snapshots remain reusable if a richer backend is adopted.

data/docs/architecture/decisions/0007-compose-customization.md

@@ -0,0 +1,30 @@
+# ADR 0007: Managed Compose customization boundary
+
+- Status: accepted
+- Date: 2026-08-14
+
+## Context
+
+The fixed PostgreSQL and Redis generators are safe and convenient, but cannot express every operational Docker
+setting. Making arbitrary YAML fragments part of the core configuration would duplicate the Compose schema and
+produce a weaker, less familiar interface.
+
+## Decision
+
+Managed services support three explicit modes: deterministic generated output, a generated base plus one project
+overlay, and one complete project-owned custom document. All modes pass through a single renderer, fingerprint,
+remote validation, state and recovery path.
+
+Customization files remain within the project and are subject to size, type, secret and host-boundary validation.
+Security-sensitive Compose settings fail closed unless `allow_unsafe` records an explicit operator decision.
+Inline secrets always fail. The `eject` command creates a complete custom starting point and a configuration
+backup instead of preserving compatibility with the earlier fixed blueprint internals.
+
+## Consequences
+
+- Users can express ordinary Compose settings without Kitsune Kit reimplementing the Compose schema.
+- Generated mode remains the default and safest supported path.
+- Custom mode transfers responsibility for image, health, network and volume semantics to the project.
+- Kitsune Kit tracks and restores the ordered document set, but does not claim ownership of arbitrary host
+  resources introduced through the unsafe escape hatch.
+- Docker's server-side `compose config` remains authoritative for Compose-version compatibility.

data/docs/architecture/provider-adapters.md

@@ -0,0 +1,49 @@
+# Provider and transport adapters
+
+Kitsune Kit's adapter API version is `Kitsune::Kit::Adapters::API_VERSION`, currently `1`. It is a small internal extension boundary, not a dynamic plugin system. A breaking signature or semantic change must increment this value and the corresponding JSON/event schemas when affected.
+
+## Provider contract
+
+A provider subclasses `Kitsune::Kit::Adapters::Provider` and implements:
+
+| Method | Contract |
+| --- | --- |
+| `validate_credentials!` | Return `true`, or raise a typed authentication/provider error. |
+| `validate_server_spec!(spec:)` | Check region, size and image availability without creating anything. |
+| `find_server(name:, tags:)` | Return an exact owned `ServerRecord` or `nil`; never adopt by name alone. |
+| `find_server_by_id(id:)` | Return the exact record or `nil`. |
+| `create_server(spec:)` | Create once and return the provider ID immediately. |
+| `wait_until_ready(id:, timeout:)` | Return an active record with a public IP or raise `TimeoutError`. |
+| `delete_server(id:)` | Delete by exact provider ID. |
+| DNS methods | Find/upsert/delete records while preserving exact IDs and zones. |
+
+Provider exceptions must be translated into `Kitsune::Kit::Errors` without copying tokens or raw provider response bodies into messages. Availability errors are configuration errors because the user can correct the desired spec; transient API failures remain retryable provider errors.
+The CLI `--timeout` value configures both DropletKit open/read timeouts and the separate readiness deadline.
+
+## Transport contract
+
+A transport subclasses `Kitsune::Kit::Adapters::Transport`. `execute` receives a command and a separate argument array, applies a deadline, and returns `CommandResult` with independent `stdout`, `stderr`, `exit_status` and `duration_ms`. It does not infer success from output. `upload` accepts explicit content, absolute normalized path and restrictive mode. Host-key verification belongs to the connection adapter and must never silently disable verification.
+
+## Verification
+
+The same shared examples run against `FakeProvider`/`DigitalOceanProvider` and `FakeTransport`/`NetSshTransport`. They cover credentials, spec validation, lifecycle, DNS, reachability, result shape, uploads and timeout mapping. Adapter-specific tests cover provider error translation, SSH quoting, unsafe paths, host keys and failed uploads.
+
+Run them with:
+
+```bash
+bundle exec rspec spec/adapters spec/contracts
+```
+
+Do not add a provider until it can pass these contracts and an opt-in real lifecycle test. The Hetzner
+feasibility/sequencing review and the decision not to create a premature hook system are recorded in
+[Roadmap and extension decisions](../roadmap.md).
+
+The state boundary follows the same rule: `StateStores::Store` defines the port, while `StateStore` is the locked atomic filesystem adapter and `Adapters::FakeStateStore` is the deterministic in-memory adapter. Both execute `spec/contracts/state_store_contract.rb`.
+
+`SecretStores::Store` and `Reporters::Reporter` are also explicit ports. Environment/fake secret stores and
+human/JSON/fake reporters execute their shared contracts in `spec/adapters`; fakes make complete workflow tests
+independent of the process environment and terminal.
+
+`Clock` is the time port for workflow event timestamps, monotonic durations, journals and bounded waits.
+`Adapters::FakeClock` advances deterministically without sleeping; both implementations execute
+`spec/contracts/clock_contract.rb`.

data/docs/architecture.md

@@ -0,0 +1,93 @@
+# Architecture
+
+Kitsune Kit is a desired-state infrastructure tool with two replaceable presentation layers over one domain core.
+
+```text
+Conventional CLI ─┐
+                  ├─ workflows ─ operations ─ provider / SSH / state / secrets
+Optional TUI ─────┘       │
+                          └─ domain events ─ human / JSON / TUI / run log
+```
+
+Presentation code does not create provider clients, open SSH connections or implement infrastructure rules. CLI and TUI call the same workflow objects and consume the same event stream.
+
+## Layers
+
+### Configuration and domain values
+
+`Configuration` loads/merges typed schema values and validates them before adapters are constructed. `Change`, `Plan`, `Result`, typed errors and versioned events are presentation-neutral values.
+
+### Workflows
+
+Workflows coordinate use cases:
+
+- initialize/select an environment;
+- build/apply/resume a plan;
+- inspect/doctor/rollback/destroy;
+- generate support diagnostics.
+
+They emit events but do not print. Apply uses `RunJournal` to record a compatible plan and step status for safe resume.
+
+The event vocabulary includes run/plan start and finish, operation start/progress/success/failure/skip, and warnings. All subscribers receive the same versioned event values; progress currently guarantees operation boundary percentages and can become finer-grained without changing presentations.
+
+### Operations
+
+Each operation exposes a non-mutating `plan`, idempotent `apply` and, where meaningful, ownership-aware `rollback`. Operations include server creation, versioned remote scripts, services and DNS.
+
+An operation verifies its result before writing a managed marker/state. Destructive replacement appears in the plan and is never applied implicitly.
+
+### Ports and adapters
+
+- `Provider`: server-spec validation, exact server/DNS lookup, create/wait/delete and credential validation.
+- `Transport`: reachability, command execution with separate output/status/timing, and safe upload.
+- `StateStores::Store`: read/update/delete and per-environment mutation-lock port; filesystem and in-memory fake adapters share a contract.
+- `SecretStores::Store`: resolves secret values without adding them to domain configuration/state; environment
+  and deterministic fake adapters execute the same contract.
+- `Reporters::Reporter`: event-consumer port for human output, stable JSON, TUI state and redacted logs.
+- `Clock`: UTC wall time, monotonic durations and sleeping, with a deterministic nonblocking fake.
+
+Real DigitalOcean/Net::SSH adapters and deterministic fakes satisfy shared contracts. This permits full workflow failure injection without a VPS while reserving real behavior for integration/E2E suites.
+
+The public adapter contract is versioned as `Kitsune::Kit::Adapters::API_VERSION`. See [Provider and transport adapters](architecture/provider-adapters.md).
+
+## State and ownership
+
+State schema version 1 contains environment, timestamps, resource identities, operation history and run journals. The server provider ID is recorded immediately after creation. DNS records are persisted one at a time. Remote resources carry script/config fingerprints and previous-state metadata.
+
+State updates acquire a per-environment file lock, validate the whole document, preserve a backup, fsync a restricted temporary file and atomically rename it. Unsupported schemas/environment mismatches are rejected.
+
+Names/tags help find resources, but provider IDs plus recorded ownership authorize destructive operations.
+
+## Remote execution
+
+Remote setup is stored in versioned Bash files under `lib/kitsune/kit/scripts`. `RemoteScript` fingerprints script bytes plus validated arguments, compares a remote marker, uploads through stdin-safe base64 transport, applies, verifies and records the marker.
+
+SSH host verification is explicit. Commands and arguments are distinct at the transport boundary. Root and deploy transports are selected per operation; user bootstrap rollback deliberately uses root access.
+
+Safety-critical SSH/firewall operations execute inside one preserved authenticated transport session while their postconditions are tested through separate fresh connections. The preserved session restores the captured policy if either fresh check fails.
+
+## Services
+
+`EnsureService` composes smaller collaborators for generated, overlay or custom Compose YAML, file
+transactions/backups, firewall reconciliation, data backup and state transitions. The ordered Compose file set is
+fingerprinted and persisted so recovery can restart the prior definition. Data lifecycle is deliberately separate
+from container/config lifecycle.
+
+An enabled service in `external` mode is configuration metadata, not an operation. It is visible through the
+CLI but excluded from VPS plans, Docker, firewall, doctor port checks and destructive lifecycle methods.
+
+## TUI
+
+The initial TUI is a pure-Ruby ANSI backend with deterministic renderer/store/controller boundaries. It has no native dependency and can be replaced without changing workflows. Headless tests feed events and keys into the store/controller and compare stable rendered buffers.
+
+## Decisions
+
+Detailed accepted decisions are in [architecture/decisions](architecture/decisions):
+
+- product boundary and direct 0.5 rewrite;
+- core/interface separation;
+- configuration/state/secrets;
+- supported platforms;
+- operation semantics;
+- optional TUI backend.
+- managed Compose customization boundary.

data/docs/commands.md

@@ -0,0 +1,224 @@
+# Command reference
+
+The authoritative runtime reference is `kit help`, `kit help COMMAND` and the equivalent `kit COMMAND help`.
+This document explains the semantics and automation contract that short help cannot capture.
+
+## Global options
+
+Global options may be passed to infrastructure commands:
+
+| Option | Meaning |
+| --- | --- |
+| `-e`, `--env NAME` | Select an environment for this invocation. |
+| `--root PATH` | Project root containing `.kitsune/`. Defaults to the current directory. |
+| `--config PATH` | Use an alternative base configuration file. |
+| `--format human|json` | Select human or versioned machine output. |
+| `--no-color` | Disable ANSI styling. `NO_COLOR` is also respected by the entrypoint environment. |
+| `--no-input` | Never prompt; fail with an actionable error when confirmation is required. |
+| `--yes` | Approve reviewed, non-destructive changes. It never confirms permanent data/server destruction. |
+| `--dry-run` | Build/display the plan without applying it. |
+| `--quiet` | Limit human output to important findings and summaries. |
+| `--verbose` | Include additional domain-event detail. |
+| `--debug` | Include technical context/stack information for failures. |
+| `--log` / `--no-log` | Enable/disable restricted redacted local logs. Enabled by default. |
+| `--timeout SECONDS` | Upper bound for each remote step, provider HTTP request and readiness wait; must be positive. |
+| `--trust-host-key SHA256:...` | Trust only this exact first-seen SSH fingerprint. |
+
+## Core workflow
+
+### `kit init [--force]`
+
+Creates `.kitsune/config.yml`, a development overlay and environment selection. Existing generated files cause exit 9 unless `--force` is explicit. It also appends runtime artifacts to `.gitignore`.
+
+### `kit doctor`
+
+Read-only checks include Ruby/runtime, configuration, SSH-key permissions, security defaults, provider credentials, state schema, exact server ownership, verified SSH access, Ubuntu version, passwordless sudo, Docker/Compose, listening ports and managed drift.
+
+Statuses are `pass`, `warn`, or `fail`. Warnings do not make the command fail; any failed check returns exit 1.
+
+### `kit plan`
+
+Calculates changes without mutation. Details exclude provider key IDs and secrets. Actions are `create`, `update`, `delete` and `no_change`; plans flag destructive changes.
+
+### `kit apply`
+
+Builds a fresh plan, displays it, rejects destructive replacement and asks for confirmation. `--yes --no-input` is the automation form. `--dry-run` guarantees no mutation.
+
+Every run and step is journaled. The provider ID is saved immediately after server creation; remote markers and local state are saved after verified operations.
+Human output ends with the redacted local log path and a post-apply `doctor`/zero-change-plan next step. Failed or
+cancelled applies report the last confirmed step, run ID and exact `kit resume RUN_ID` command. JSON carries the
+same guidance as a `warning_emitted` event and never receives an extra human-output line.
+
+### `kit resume [RUN_ID]`
+
+Resumes the named run or latest incomplete run. It rejects successful runs and saved operation sets that no longer match configuration. Completed steps are skipped. Confirmation is required (`--yes` in automation).
+
+### `kit status`
+
+Displays the selected environment, exact provider server and locally tracked resources. It does not run remote diagnostics; use `doctor` for that.
+
+### `kit rollback`
+
+Runs rollback in reverse dependency order for resources recorded as managed. It preserves the Droplet and service data volumes. It is not a universal snapshot restore: provider resources or pre-existing files that Kitsune Kit never owned are not touched.
+
+## Server
+
+```text
+kit server show
+kit server status
+kit server create
+kit server configure
+kit server ssh
+kit server import --provider-id DROPLET_ID --confirm-import SERVER_NAME
+kit server destroy --confirm-destroy SERVER_NAME
+```
+
+- `show`/`status`: inspect server and state.
+- `create`: apply only the server operation.
+- `configure`: apply remote, service and DNS operations after the server operation.
+- `ssh`: verify the managed connection, then replace the process with the system `ssh` client using strict known-host checking.
+- `import`: recover only the server identity after state loss. It requires an exact numeric Droplet ID and configured server-name confirmation, then verifies name, tags, region, size, image, active status and public IP. It never imports remote-resource ownership.
+- `destroy`: delete only the exact recorded provider ID after verifying name/tags, then restore/remove managed DNS and clear state. If provider deletion fails, DNS is left untouched; if DNS cleanup fails afterward, retrying completes cleanup without deleting a second server. It never deletes by name alone.
+
+Interactive destruction asks the operator to type the exact server name. Automation must use `--confirm-destroy SERVER_NAME`; `--yes` is insufficient.
+Before an interactive confirmation, Kitsune Kit prints the environment, provider, resource, recorded provider ID and recoverability. JSON confirmation errors include the same safe target context.
+
+## Docker
+
+```text
+kit docker status
+kit docker install
+kit docker uninstall --yes
+```
+
+Uninstall refuses to run while managed services remain. Docker installation uses the official apt repository and creates the `kitsune-private` network.
+
+## Services
+
+```text
+kit service postgres status
+kit service postgres install
+kit service postgres backup
+kit service postgres remove --yes
+kit service postgres destroy-data --backup-before-destroy --confirm-destroy postgres@ENV
+kit service postgres compose show
+kit service postgres compose validate
+kit service postgres compose diff
+kit service postgres compose eject
+```
+
+Replace `postgres` with `redis` for Redis.
+
+- `install`: service must be enabled and its secret environment variable present.
+- `backup`: pauses the service, creates a restricted tar archive of the volume on the server and always unpauses it.
+- `remove`: removes containers/network attachment and firewall rules owned by Kitsune Kit, but keeps the volume and managed files needed for recovery.
+- `destroy-data`: optionally creates a restricted data archive, then removes containers, volume, owned
+  configuration backups/files and state. In an interactive terminal it offers the backup and requires typing
+  `TYPE@ENV`; automation can request it with `--backup-before-destroy` and must supply `--confirm-destroy`.
+  The data archive is retained outside the service directory, but must be copied to independent storage.
+- `compose show`: print the exact generated/custom documents that would be uploaded, without resolving secrets.
+- `compose validate`: parse the configured YAML and run Kitsune Kit's local structure and security checks.
+- `compose diff`: compare the desired Compose fingerprint with the last applied state. An older state without a
+  Compose fingerprint is reported as not installed/unknown rather than guessed.
+- `compose eject`: write `.kitsune/compose/TYPE.yml`, back up `config.yml` as `config.yml.backup`, and switch the
+  service to `custom`. It refuses existing targets unless `--force` is explicit.
+
+When an enabled service has `mode: external`, `status` returns only its configured host/port and
+`managed: false`. All local lifecycle actions fail safely; Kitsune Kit never treats an external provider's data as
+a VPS Docker volume.
+
+`install` and `apply` additionally run `docker compose config --quiet` on the server before starting containers.
+For overlay mode every `--file` is passed in deterministic base-then-overlay order. See
+[Compose customization](services/compose.md).
+
+## DNS
+
+```text
+kit dns list
+kit dns plan
+kit dns apply
+kit dns remove --yes
+```
+
+DNS operations use exact record IDs and store original values. `remove` restores updated records and deletes only records created by Kitsune Kit.
+
+## Environments
+
+```text
+kit env list
+kit env current
+kit env use NAME
+```
+
+`use` validates that `.kitsune/environments/NAME.yml` exists and writes the selection atomically. An explicit `--env`/`KITSUNE_ENV` wins without changing the persisted selection.
+
+## Support
+
+```bash
+kit support bundle
+```
+
+The human-readable command prints the complete redacted bundle after writing it, so it can be reviewed before
+sharing. JSON mode returns the local path without adding non-JSON output. Kitsune Kit never uploads the bundle.
+
+Creates a permission-restricted JSON file under `.kitsune/support/` with versions, platform, redacted configuration/state, doctor results and selected redacted logs. The path is printed; Kitsune Kit never uploads it. Inspect it before sharing.
+
+## TUI
+
+`kit ui` starts the optional full-screen interface. Bare `kit` does the same only with interactive stdin/stdout; otherwise it prints help. See [TUI](tui.md).
+
+## Version
+
+`kit version`, `kit --version` and `kit -v` print the installed Kitsune Kit version without loading project configuration or contacting a provider.
+
+## JSON output
+
+Successful workflow documents use schema version 1 and include:
+
+```json
+{
+  "schema_version": 1,
+  "command": "plan",
+  "environment": "production",
+  "run_id": "...",
+  "status": "success",
+  "duration_ms": 12,
+  "result": {},
+  "warnings": [],
+  "events": []
+}
+```
+
+Errors are JSON on standard error:
+
+```json
+{
+  "schema_version": 1,
+  "status": "failure",
+  "error": {
+    "code": "configuration_error",
+    "message": "...",
+    "hint": "...",
+    "context": {}
+  }
+}
+```
+
+Treat unknown additive keys as forward-compatible, but reject unsupported `schema_version` values in consumers.
+
+## Exit codes
+
+| Code | Meaning |
+| ---: | --- |
+| 0 | Success, including a no-change plan/apply. |
+| 1 | Unexpected failure or failed `doctor` check. |
+| 2 | Invalid CLI syntax/unknown command. |
+| 3 | Invalid/missing configuration or unsupported environment. |
+| 4 | Authentication failure. |
+| 5 | Provider API failure. |
+| 6 | SSH/network connection failure. |
+| 7 | Remote command failure. |
+| 8 | Post-change verification failure. |
+| 9 | Unsafe operation or missing confirmation. |
+| 10 | Timeout. |
+| 130 | Interrupted by `SIGINT`. |