kitsune-kit 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02a64110c8bffb9342d3cd0550360d95d871a4c1179f33899e34787abe59a080
-  data.tar.gz: 2bf327e34d000c12ba3883573a088493f353f5265ca2b7aa4693b645ba9f3ee9
+  metadata.gz: '08f2d244f1d6869964e8722fe07a91e1fd84c8786d56faf3a6d92e5ffedeca03'
+  data.tar.gz: f8f5090aa7cb0f7bf3782c35564339dbf5891b675a96e538d99ab57a295334b9
 SHA512:
-  metadata.gz: 23e94dae8106856bd149f8e66d47ee61c47d1ddb5ccbb3311ec8f214d0874b4cdf64b40777d7f6dd04b393be684044785e6135f23f78618237ba5e6927e317cb
-  data.tar.gz: 59f168aa081fc7047a0e49a1107c288cdd4f2c04e0da45be46e514c89e181ee023e1f860ceb2511017e1f9885e9c2a773a6008959a9c3c78ff15e49bf75f8750
+  metadata.gz: 8a09c75539d4ec1cd52bd18aaac184a26491ea770044ef4e0a39ee9dd8057851c3a60944fb51b64173f23c24f36f4f79450d804b89e1ab211861089ef2b853a1
+  data.tar.gz: fceed8d60ab1d391ac09e9346ea383722e2407870a913a548eb73e782c29d704b19590859309be147a9f5ff794edd5e45a4a0bba007fdea5b7ae699eb09586a3

data/CHANGELOG.md

@@ -5,6 +5,31 @@ and [Semantic Versioning](https://semver.org/); minor releases may change public
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-14
+
+### Added
+
+- Generated, overlay and fully custom Docker Compose modes for managed PostgreSQL and Redis.
+- Local `compose show`, `validate`, `diff` and safe `eject` service commands.
+- Project-bound file validation, inline-secret detection and explicit review metadata for unsafe Compose options.
+- Multi-file upload, fingerprinting, state tracking, recovery and rollback for Compose customizations.
+- Unit coverage for each customization mode, security boundary, ejection and remote multi-file execution.
+
+### Changed
+
+- Initialized projects now declare the generated Compose mode explicitly.
+- Service state records the Compose mode, ordered file set and content fingerprint.
+- Kitsune Kit 0.6.0 replaces the fixed service blueprints directly; no legacy blueprint compatibility layer remains.
+
+### Fixed
+
+- Keep local Compose inspection, validation, diff and ejection independent from provider and service credentials.
+
+### Security
+
+- Customizations reject host namespace/device access, elevated capabilities, unmanaged ports, bind mounts, remote
+  builds, unmanaged env files and inline secrets unless the documented explicit unsafe escape applies.
+
 ## [0.5.0] - 2026-08-14
 
 ### Added
@@ -111,7 +136,8 @@ and [Semantic Versioning](https://semver.org/); minor releases may change public
 - First public preview.
 - Bootstrap commands for DigitalOcean, Docker and PostgreSQL.
 
-[Unreleased]: https://github.com/omarhrra/kitsune-kit/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/omarhrra/kitsune-kit/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/omarhrra/kitsune-kit/compare/v0.5.0...v0.6.0
 [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

data/README.md

@@ -2,14 +2,14 @@
 
 Kitsune Kit prepares Ubuntu servers for Docker and Kamal deployments through a predictable, inspectable CLI.
 
-> 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.
+> Status: `0.6.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.
 
 ## 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.
+- Optionally installs private PostgreSQL/Redis services, with generated, overlay or fully custom Docker Compose.
 - 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.
@@ -32,7 +32,7 @@ gem install kitsune-kit
 Or add it to a project:
 
 ```ruby
-gem "kitsune-kit", "~> 0.5.0"
+gem "kitsune-kit", "~> 0.6.0"
 ```
 
 ## Safe quick start
@@ -72,6 +72,7 @@ See [Getting started](docs/getting-started.md) for the complete first-run proced
 | `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 service TYPE compose ACTION` | Show, validate, diff or eject Compose | Local |
 | `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 |
@@ -118,6 +119,9 @@ kit service postgres install
 
 See [PostgreSQL](docs/services/postgres.md) and [Redis](docs/services/redis.md).
 
+Compose remains generated and secure by default. Use an overlay for ordinary Docker options or eject a complete,
+editable file when the generated model is no longer sufficient. See [Compose customization](docs/services/compose.md).
+
 ## CLI and optional TUI
 
 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`.
@@ -151,6 +155,7 @@ Docker-backed integration tests and credential-gated DigitalOcean E2E tests are
 - [Getting started](docs/getting-started.md)
 - [Configuration](docs/configuration.md)
 - [Command reference](docs/commands.md)
+- [Compose customization](docs/services/compose.md)
 - [Security](docs/security.md)
 - [Manual security audit](docs/security-audit.md)
 - [Troubleshooting](docs/troubleshooting.md)

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.md

@@ -68,7 +68,10 @@ Safety-critical SSH/firewall operations execute inside one preserved authenticat
 
 ## Services
 
-`EnsureService` composes smaller collaborators for generated Compose YAML, file transaction/backups, firewall reconciliation, data backup and state transitions. Data lifecycle is deliberately separate from container/config lifecycle.
+`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.
@@ -87,3 +90,4 @@ Detailed accepted decisions are in [architecture/decisions](architecture/decisio
 - supported platforms;
 - operation semantics;
 - optional TUI backend.
+- managed Compose customization boundary.

data/docs/commands.md

@@ -101,6 +101,10 @@ 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.
@@ -112,11 +116,21 @@ Replace `postgres` with `redis` for Redis.
   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

data/docs/configuration.md

@@ -66,6 +66,10 @@ services:
     allowed_cidrs: []
     port: 5432
     password_env: POSTGRES_PASSWORD
+    compose:
+      mode: generated
+      file:
+      allow_unsafe: false
   redis:
     enabled: false
     mode: managed
@@ -76,6 +80,10 @@ services:
     allowed_cidrs: []
     port: 6379
     password_env: REDIS_PASSWORD
+    compose:
+      mode: generated
+      file:
+      allow_unsafe: false
 
 system:
   swap_size_gb: 2
@@ -135,6 +143,9 @@ SSH policy is ordered to keep a verified path open: create/verify the deploy use
 | `allowed_cidrs` | Required and non-empty when `publish` is true. |
 | `port` | Host port, 1–65535. Container ports remain 5432/6379. |
 | `password_env` | Environment-variable name containing the required secret. |
+| `compose.mode` | `generated`, `overlay`, or `custom`; only valid for managed services. |
+| `compose.file` | Project-local YAML file required by `overlay` and `custom`; empty for `generated`. |
+| `compose.allow_unsafe` | Explicit opt-in for security-sensitive Compose options. Defaults to false. |
 
 Images, binds, ports and secret names reject newline/shell/YAML injection patterns before any SSH connection is opened.
 
@@ -155,6 +166,11 @@ status` reports the endpoint without its secret. Install, backup, remove and des
 availability, TLS, backups and destruction with the external provider. External services never add Docker,
 firewall or private-port checks to the VPS plan.
 
+Compose files must be regular, non-symlink files inside the project root and no larger than 256 KiB. `overlay`
+combines the generated base with the configured file; `custom` replaces the generated document and must define
+`services.postgres` or `services.redis` respectively. Inline secrets are rejected. See
+[Compose customization](services/compose.md) for examples, validation rules and commands.
+
 ### `system`
 
 | Field | Validation |

data/docs/services/compose.md

@@ -0,0 +1,164 @@
+# Compose customization
+
+Kitsune Kit can manage PostgreSQL and Redis with a generated Compose document, a user overlay, or a complete
+custom document. All three modes use the same `plan`, `apply`, state, recovery, rollback and data-safety workflow.
+The TUI is optional; these features are fully available through ordinary CLI commands.
+
+## Choosing a mode
+
+| Mode | Kitsune Kit generates the base | Your file | Best use |
+| --- | --- | --- | --- |
+| `generated` | Yes | None | Secure defaults with image, port and password settings controlled by `config.yml`. |
+| `overlay` | Yes | Compose override | Add labels, resource limits, logging, environment options or other supported overrides. |
+| `custom` | No | Complete Compose document | Take direct ownership of the service definition while retaining Kitsune Kit lifecycle management. |
+
+Start with `generated`. Prefer `overlay` while the base service, volume, network and health check still fit. Use
+`custom` when you need to replace those assumptions. There is no legacy-blueprint compatibility layer.
+
+## Generated mode
+
+```yaml
+services:
+  postgres:
+    compose:
+      mode: generated
+      file:
+      allow_unsafe: false
+```
+
+The generated document is deterministic. Passwords appear only as `${POSTGRES_PASSWORD}` or
+`${REDIS_PASSWORD}` references; their values are uploaded separately in a mode-`0600` `.env` file.
+
+## Overlay mode
+
+Create a project file such as `.kitsune/compose/postgres.override.yml`:
+
+```yaml
+services:
+  postgres:
+    environment:
+      LOG_STATEMENT: ddl
+    logging:
+      options:
+        max-size: 20m
+        max-file: "5"
+    deploy:
+      resources:
+        limits:
+          memory: 1G
+```
+
+Reference it from configuration:
+
+```yaml
+services:
+  postgres:
+    compose:
+      mode: overlay
+      file: .kitsune/compose/postgres.override.yml
+      allow_unsafe: false
+```
+
+Kitsune Kit uploads `compose.yml` followed by `compose.override.yml` and supplies both to every Docker Compose
+command in that order. Changes to either document change the plan fingerprint.
+
+## Custom mode and eject
+
+Create a complete starting document automatically:
+
+```bash
+kit service postgres compose eject
+```
+
+This operation:
+
+1. writes `.kitsune/compose/postgres.yml` from the current generated definition;
+2. copies `.kitsune/config.yml` to `.kitsune/config.yml.backup`;
+3. changes the service to `compose.mode: custom` and references the new file.
+
+Existing output or backup files are not overwritten. Review both and use `--force` only when replacement is
+intentional. YAML comments in `config.yml` may be reformatted by ejection; the byte-for-byte backup is retained.
+
+A custom PostgreSQL file must contain `services.postgres`; Redis must contain `services.redis`. Configuration
+fields such as `image` no longer alter a custom document, but `password_env`, publication/firewall policy and
+lifecycle state remain part of Kitsune Kit's safety model.
+
+## Inspecting and validating
+
+```bash
+kit service postgres compose show
+kit service postgres compose validate
+kit service postgres compose diff
+kit service postgres compose show --format json
+```
+
+- `show` displays the exact ordered documents and their sources.
+- `validate` parses YAML, validates the required service and applies local security policy.
+- `diff` compares desired content with the last successfully applied Compose fingerprint.
+- `plan` includes mode, ordered files, findings and the overall service fingerprint.
+- `apply` uploads restricted files and runs `docker compose config --quiet` remotely before `up`.
+
+Local validation does not replace Docker's own validation. A customization can pass local checks but fail because
+an option is unsupported by the Docker Compose version on the VPS; `apply` then recovers the previous managed
+files and attempts to restart the previous file set.
+
+## File boundary
+
+Customization files must:
+
+- be inside `--root` after path expansion and resolution;
+- be regular files, not symlinks;
+- be at most 256 KiB;
+- contain a top-level YAML mapping;
+- avoid YAML aliases.
+
+These constraints keep the deployment input reviewable and prevent a project configuration from reading an
+arbitrary local file.
+
+## Secrets
+
+Never put a secret value in Compose YAML. Sensitive mapping keys and `KEY=value` environment-list entries are
+rejected unless the value is a `${VARIABLE_NAME}` reference.
+
+```yaml
+services:
+  postgres:
+    environment:
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+```
+
+Export the variable before `doctor`, `plan`, `apply` or `install`. Compose display/JSON output never resolves its
+value. The remote `.env`, Compose documents and backups use restricted permissions.
+
+## Unsafe options
+
+The local policy flags options that cross Kitsune Kit's normal isolation boundary, including:
+
+- privileged containers and host PID/IPC/network namespaces;
+- `ALL`, `SYS_ADMIN`, `SYS_PTRACE` or `NET_ADMIN` capabilities;
+- host devices, absolute bind mounts and the Docker socket;
+- ports outside the exact configured bind/port/firewall model;
+- remote `build` contexts and unmanaged `env_file` references.
+
+By default, any finding stops `show`, `validate`, `plan` and `apply`. If the configuration is intentionally outside
+the standard boundary, review every finding and set:
+
+```yaml
+compose:
+  mode: custom
+  file: .kitsune/compose/postgres.yml
+  allow_unsafe: true
+```
+
+This is an escape hatch, not a promise that Kitsune Kit manages or reverses the extra host resources. Findings
+remain visible in metadata and plan details. Inline secrets are always rejected and cannot be enabled by
+`allow_unsafe`.
+
+## Rollback behavior
+
+State records the mode, ordered filenames and content fingerprint after a verified apply. Before an update,
+Kitsune Kit backs up all currently tracked and desired Compose files plus `.env`. A failed apply removes the new
+file set, restores the backup and starts the prior ordered file set. `kit rollback` uses the same recorded set.
+
+Docker volumes remain governed by the existing service contract: `remove` preserves data and `destroy-data`
+requires exact confirmation. Compose customization does not broaden deletion ownership.

data/lib/kitsune/kit/cli.rb

@@ -205,17 +205,24 @@ module Kitsune
         end
       end
 
-      desc "service TYPE ACTION", "Manage postgres or redis: status, install, backup, remove, destroy-data"
+      desc "service TYPE ACTION [SUBACTION]",
+           "Manage postgres or redis, including Compose show, validate, diff and eject"
       option :confirm_destroy, type: :string, desc: "Exact TYPE@ENV value required for data destruction"
       option :backup_before_destroy, type: :boolean, default: false,
                                      desc: "Create a restricted remote data backup before destroy-data"
-      def service(type, action)
+      option :force, type: :boolean, default: false, desc: "Replace an existing ejected Compose file and backup"
+      def service(type, action, subaction = nil)
         execute do
-          app, reporter = build_application
-          operation = find_service_operation(app, type, action)
-          result = dispatch_service_action(app, operation, type, action)
+          app, reporter = action == "compose" ? build_local_application : build_application
+          result = if action == "compose"
+                     dispatch_service_compose(app, type, subaction)
+                   else
+                     operation = find_service_operation(app, type, action)
+                     dispatch_service_action(app, operation, type, action)
+                   end
           if json? && result.is_a?(Result)
-            flush_json(reporter, result, "service.#{type}.#{action}", app.config.environment)
+            command = ["service", type, action, subaction].compact.join(".")
+            flush_json(reporter, result, command, app.config.environment)
           end
           0
         end
@@ -345,6 +352,21 @@ module Kitsune
           [app, reporter]
         end
 
+        def build_local_application
+          filter = @secret_filter = build_secret_filter
+          bus = Events::Bus.new
+          reporter = build_reporter(filter)
+          bus.subscribe(reporter)
+          subscribe_logger(bus, filter)
+          config = Configuration::Loader.new(
+            root: options[:root], env: ENV, config_path: options[:config], validate_secrets: false
+          ).load(environment: options[:env])
+          app = Application.new(config: config, provider: nil, state_store: StateStore.new(root: options[:root]),
+                                event_bus: bus)
+          register_configured_secrets(filter, config)
+          [app, reporter]
+        end
+
         def build_tui
           unless $stdin.tty? && $stdout.tty?
             raise Errors::ConfigurationError.new(
@@ -475,6 +497,61 @@ module Kitsune
           end
         end
 
+        def dispatch_service_compose(app, type, action)
+          raise Errors::ConfigurationError, "unknown service type: #{type}" unless %w[postgres redis].include?(type)
+
+          service = app.config.services.public_send(type)
+          if service.mode == "external"
+            raise Errors::UnsafeOperationError, "Compose is not managed for an external #{type} service"
+          end
+
+          compose = ServiceCompose.new(config: app.config, type: type, service: service)
+          case action
+          when "show" then compose_show(compose)
+          when "validate" then compose_validate(type, compose)
+          when "diff" then compose_diff(app, type, compose)
+          when "eject" then compose_eject(app, type)
+          else
+            raise Errors::ConfigurationError,
+                  "unknown Compose action: #{action || '(missing)'}; expected show, validate, diff or eject"
+          end
+        end
+
+        def compose_show(compose)
+          puts compose.display unless json?
+          Result.success(compose.metadata.merge(content: compose.display, fingerprint: compose.fingerprint))
+        end
+
+        def compose_validate(type, compose)
+          puts "#{type} Compose customization is valid (#{compose.mode})." unless json?
+          Result.success(compose.metadata.merge(valid: true, fingerprint: compose.fingerprint))
+        end
+
+        def compose_eject(app, type)
+          value = Workflows::EjectCompose.new(
+            root: options[:root], config: app.config, type: type, config_path: options[:config]
+          ).call(force: options[:force])
+          puts "Created #{value[:compose_file]} and updated #{value[:config_file]}." unless json?
+          Result.success(value)
+        end
+
+        def compose_diff(app, type, compose)
+          state = app.state_store.read(app.config.environment).dig("resources", "service.#{type}")
+          installed = state&.fetch("compose_fingerprint", nil)
+          changed = installed != compose.fingerprint
+          value = { changed: changed, desired_fingerprint: compose.fingerprint,
+                    installed_fingerprint: installed, mode: compose.mode }
+          unless json?
+            label = if installed
+                      changed ? "changed" : "unchanged"
+                    else
+                      "not installed or from an older state"
+                    end
+            puts "#{type} Compose: #{label}"
+          end
+          Result.success(value)
+        end
+
         def destroy_service_data(app, operation, type)
           expected = "#{type}@#{app.config.environment}"
           state = app.state_store.read(app.config.environment).dig("resources", "service.#{type}")