nvoi 0.1.8 → 0.2.0

data/.claude/todo/refactor/05-external.md

@@ -1,133 +0,0 @@
-# 05 - External: SSH, Kubectl, Containerd
-
-## Priority: THIRD (parallel with cloud/dns)
-
----
-
-## Current State
-
-| File                       | Lines | Purpose                      |
-| -------------------------- | ----- | ---------------------------- |
-| `remote/ssh_executor.rb`   | 73    | SSH command execution        |
-| `remote/docker_manager.rb` | 204   | Docker/containerd operations |
-| `remote/volume_manager.rb` | 104   | Volume mount operations      |
-| `k8s/renderer.rb`          | 45    | kubectl apply wrapper        |
-
-**Total: ~426 lines across 4 files**
-
----
-
-## Target Structure
-
-```
-lib/nvoi/external/
-├── ssh.rb              # SSH executor
-├── kubectl.rb          # kubectl wrapper (from k8s/renderer.rb)
-└── containerd.rb       # containerd/Docker operations (from docker_manager.rb + volume_manager.rb)
-```
-
----
-
-## What Each Does
-
-### SSH Executor (`remote/ssh_executor.rb`)
-
-- `execute(command, stream: false)` → String
-- `execute_quiet(command)` → nil (ignore errors)
-- `open_shell` → exec into SSH
-
-### Docker Manager (`remote/docker_manager.rb`)
-
-- `create_network(name)`
-- `build_image(path, tag, cache_from)` → local build, rsync, ctr import
-- `run_container(opts)`
-- `exec(container, command)`
-- `wait_for_health(opts)`
-- `container_status(name)`, `container_logs(name, lines)`
-- `stop_container(name)`, `remove_container(name)`
-- `list_containers(filter)`, `list_images(filter)`
-- `cleanup_old_images(prefix, keep_tags)`
-- `container_running?(name)`
-- `setup_cloudflared(network, token, name)`
-
-### Volume Manager (`remote/volume_manager.rb`)
-
-- `mount(opts)` → format + mount + fstab
-- `unmount(mount_path)`
-- `mounted?(mount_path)`
-- `remove_from_fstab(mount_path)`
-
-### K8s Renderer (`k8s/renderer.rb`)
-
-- `render_template(name, data)` → String
-- `apply_manifest(ssh, template_name, data)` → kubectl apply
-- `wait_for_deployment(ssh, name, namespace, timeout)`
-
----
-
-## DRY Opportunities
-
-### 1. Rename docker_manager → containerd
-
-It's not really Docker anymore. It uses `ctr` (containerd). Name it accurately:
-
-```ruby
-# external/containerd.rb
-class Containerd
-  def initialize(ssh) ... end
-  def build_and_import(path, tag) ... end
-  def list_images(filter) ... end
-  def cleanup_images(prefix, keep_tags) ... end
-end
-```
-
-### 2. Extract Volume Logic
-
-Volume mounting is separate from container runtime. Could stay in containerd or be separate.
-Decision: Keep in containerd since it's all "server-side stuff via SSH".
-
-### 3. Simplify K8s Renderer
-
-Move template rendering to `utils/templates.rb`. Keep only kubectl operations:
-
-```ruby
-# external/kubectl.rb
-class Kubectl
-  def initialize(ssh) ... end
-  def apply(manifest) ... end
-  def wait_for_deployment(name, namespace, timeout) ... end
-  def wait_for_statefulset(name, namespace, timeout) ... end
-  def get_pod_name(label) ... end
-  def exec(pod, command) ... end
-end
-```
-
-### 4. SSH as Dependency
-
-All external adapters that run on remote servers need SSH:
-
-- `Containerd.new(ssh)`
-- `Kubectl.new(ssh)`
-- `VolumeManager.new(ssh)` (if kept separate)
-
-This is correct. SSH is the transport, others are domain-specific.
-
----
-
-## Migration Steps
-
-1. Move `remote/ssh_executor.rb` → `external/ssh.rb`
-2. Rename `remote/docker_manager.rb` → `external/containerd.rb`
-3. Merge `remote/volume_manager.rb` into `external/containerd.rb` (or keep separate)
-4. Extract kubectl operations from `k8s/renderer.rb` → `external/kubectl.rb`
-5. Move template rendering to `utils/templates.rb` (already planned in 02-utils.md)
-6. Update namespace from `Remote::SSHExecutor` to `External::SSH`
-
----
-
-## Estimated Effort
-
-- **Lines to consolidate:** ~426
-- **Files created:** 3
-- **Files deleted:** 4
-- **DRY savings:** ~30 lines (simplified renderer, naming cleanup)

data/.claude/todo/refactor/06-cli.md

@@ -1,123 +0,0 @@
-# 06 - CLI Entry Point (Thor Routing)
-
-## Priority: FOURTH
-
-CLI depends on all command implementations.
-
----
-
-## Current State
-
-| File     | Lines | Purpose                                   |
-| -------- | ----- | ----------------------------------------- |
-| `cli.rb` | 191   | Thor commands + CredentialsCLI subcommand |
-
----
-
-## Target Structure
-
-```
-lib/nvoi/
-└── cli.rb              # Thor routing only (~50 lines)
-```
-
----
-
-## What CLI Currently Does
-
-1. **Thor setup** - class options, exit behavior
-2. **Command definitions** - `deploy`, `delete`, `exec`, `credentials`
-3. **Config path resolution** - `resolve_config_path`, `resolve_working_dir`
-4. **Instantiate services** - creates `DeployService`, `DeleteService`, etc.
-
----
-
-## Target: Thin Router
-
-CLI should ONLY:
-
-1. Define Thor commands
-2. Parse options
-3. Delegate to `cli/<command>/command.rb`
-
-```ruby
-# cli.rb
-module Nvoi
-  class CLI < Thor
-    class_option :config, aliases: "-c", default: "deploy.enc"
-    class_option :dir, aliases: "-d", default: "."
-
-    desc "deploy", "Deploy application"
-    option :dockerfile_path
-    def deploy
-      require_relative "cli/deploy/command"
-      CLI::Deploy::Command.new(options).run
-    end
-
-    desc "delete", "Delete infrastructure"
-    def delete
-      require_relative "cli/delete/command"
-      CLI::Delete::Command.new(options).run
-    end
-
-    desc "exec [COMMAND...]", "Execute command on server"
-    option :server, default: "main"
-    option :all, type: :boolean
-    option :interactive, aliases: "-i", type: :boolean
-    def exec(*args)
-      require_relative "cli/exec/command"
-      CLI::Exec::Command.new(options).run(args)
-    end
-
-    desc "credentials SUBCOMMAND", "Manage credentials"
-    subcommand "credentials", CLI::Credentials
-  end
-
-  class CLI::Credentials < Thor
-    desc "edit", "Edit encrypted credentials"
-    def edit
-      require_relative "cli/credentials/edit/command"
-      CLI::Credentials::Edit::Command.new(options).run
-    end
-
-    desc "show", "Show decrypted credentials"
-    def show
-      require_relative "cli/credentials/show/command"
-      CLI::Credentials::Show::Command.new(options).run
-    end
-  end
-end
-```
-
----
-
-## DRY Opportunities
-
-### 1. Move Logic to Commands
-
-All the `resolve_config_path`, validation, service instantiation moves INTO each command.
-
-### 2. Lazy Requires
-
-Use `require_relative` inside methods. Faster CLI startup, only loads what's needed.
-
-### 3. CredentialsCLI → Nested Class
-
-Currently separate class, can be nested under CLI.
-
----
-
-## Migration Steps
-
-1. Create command files first (07-10)
-2. Strip `cli.rb` down to routing only
-3. Move `CredentialsCLI` inline as `CLI::Credentials`
-4. Add lazy requires for each command
-
----
-
-## Estimated Effort
-
-- **Lines after refactor:** ~50 (down from 191)
-- **Logic moved to:** `cli/*/command.rb` files
-- **DRY savings:** 141 lines moved (not deleted, redistributed)

data/.claude/todo/refactor/07-cli-deploy-command.md

@@ -1,177 +0,0 @@
-# 07 - CLI: Deploy Command
-
-## Priority: FIFTH
-
-Depends on external adapters, utils, objects.
-
----
-
-## Current State
-
-| File                | Lines | Purpose                     |
-| ------------------- | ----- | --------------------------- |
-| `service/deploy.rb` | 81    | DeployService orchestration |
-
----
-
-## Target Structure
-
-```
-lib/nvoi/cli/deploy/
-├── command.rb          # Entry point + step orchestration
-└── steps/
-    ├── provision_network.rb
-    ├── provision_server.rb
-    ├── provision_volume.rb
-    ├── setup_k3s.rb
-    ├── configure_tunnel.rb
-    ├── build_image.rb
-    ├── deploy_database.rb
-    ├── deploy_service.rb
-    └── cleanup_images.rb
-```
-
----
-
-## What Deploy Does (Current Flow)
-
-```
-1. Load config
-2. Init provider
-3. Validate provider config
-4. provision_server:
-   a. ServerProvisioner.run → provisions network, firewall, servers
-   b. VolumeProvisioner.run → creates/attaches/mounts volumes
-   c. K3sClusterSetup.run → installs K3s on master + workers
-5. configure_tunnels:
-   a. TunnelConfigurator.run → creates Cloudflare tunnels + DNS
-6. deploy_application:
-   a. Orchestrator.run:
-      - Acquire lock
-      - ImageBuilder.build_and_push
-      - Push to registry
-      - ServiceDeployer.deploy_app_secret
-      - ServiceDeployer.deploy_database
-      - ServiceDeployer.deploy_service (for each service)
-      - ServiceDeployer.deploy_app_service (for each app)
-      - ServiceDeployer.deploy_cloudflared
-      - ServiceDeployer.verify_traffic_switchover
-      - Cleaner.cleanup_old_images
-      - Release lock
-```
-
----
-
-## Target Flow (Simplified)
-
-```ruby
-# cli/deploy/command.rb
-class Command
-  def run
-    config = Utils::ConfigLoader.new.load(config_path)
-    provider = External::Cloud.for(config)
-    log = Utils::Logger.new
-
-    Steps::ProvisionNetwork.new(config, provider, log).run
-    Steps::ProvisionServer.new(config, provider, log).run
-    Steps::ProvisionVolume.new(config, provider, log).run
-    Steps::SetupK3s.new(config, provider, log).run
-    tunnels = Steps::ConfigureTunnel.new(config, log).run
-    Steps::BuildImage.new(config, log).run
-    Steps::DeployService.new(config, tunnels, log).run
-    Steps::CleanupImages.new(config, log).run
-  end
-end
-```
-
----
-
-## DRY Opportunities
-
-### 1. Flatten the Hierarchy
-
-Current: `DeployService` → `Steps::*` → `Deployer::*`
-Target: `Command` → `Steps::*` directly
-
-Kill `Deployer::Orchestrator`. Its logic moves into `Steps::DeployService`.
-
-### 2. Remove Thin Wrappers
-
-`Steps::ApplicationDeployer` is just:
-
-```ruby
-def run
-  orchestrator = Deployer::Orchestrator.new(@config, @provider, @log)
-  orchestrator.run(@server_ip, @tunnels, @working_dir)
-end
-```
-
-Delete it. Put that logic in `Steps::DeployService`.
-
-### 3. Consolidate ServiceDeployer
-
-`Deployer::ServiceDeployer` (312 lines) does too much:
-
-- Deploy app secret
-- Deploy app service
-- Deploy database
-- Deploy generic service
-- Deploy cloudflared
-- Verify traffic
-- Run pre-run commands
-
-Split into focused steps or keep as internal helper in `Steps::DeployService`.
-
-### 4. Lock Management
-
-Deployment lock is in `Orchestrator`. Move to `Command`:
-
-```ruby
-def run
-  acquire_lock(ssh)
-  # ... steps ...
-ensure
-  release_lock(ssh)
-end
-```
-
----
-
-## Migration Steps
-
-1. Create `lib/nvoi/cli/deploy/command.rb`
-2. Create `lib/nvoi/cli/deploy/steps/` directory
-3. Move `steps/server_provisioner.rb` → `cli/deploy/steps/provision_server.rb`
-4. Move `steps/volume_provisioner.rb` → `cli/deploy/steps/provision_volume.rb`
-5. Merge `steps/k3s_cluster_setup.rb` + `steps/k3s_provisioner.rb` → `cli/deploy/steps/setup_k3s.rb`
-6. Move `steps/tunnel_configurator.rb` → `cli/deploy/steps/configure_tunnel.rb`
-7. Move `deployer/image_builder.rb` → `cli/deploy/steps/build_image.rb`
-8. Merge `deployer/orchestrator.rb` + `deployer/service_deployer.rb` → `cli/deploy/steps/deploy_service.rb`
-9. Move `deployer/cleaner.rb` → `cli/deploy/steps/cleanup_images.rb`
-10. Extract network/firewall from ServerProvisioner → `cli/deploy/steps/provision_network.rb`
-11. Delete old files: `service/deploy.rb`, `deployer/orchestrator.rb`, `steps/application_deployer.rb`
-
----
-
-## Estimated Effort
-
-**Files involved:**
-
-- `service/deploy.rb` (81 lines)
-- `steps/server_provisioner.rb` (44 lines)
-- `steps/volume_provisioner.rb` (155 lines)
-- `steps/k3s_provisioner.rb` (352 lines)
-- `steps/k3s_cluster_setup.rb` (106 lines)
-- `steps/tunnel_configurator.rb` (67 lines)
-- `steps/application_deployer.rb` (27 lines)
-- `deployer/orchestrator.rb` (147 lines)
-- `deployer/infrastructure.rb` (127 lines)
-- `deployer/image_builder.rb` (24 lines)
-- `deployer/service_deployer.rb` (312 lines)
-- `deployer/cleaner.rb` (37 lines)
-
-**Total: ~1479 lines to reorganize**
-
-- **Files created:** 9 (command.rb + 8 steps)
-- **Files deleted:** 12
-- **DRY savings:** ~150 lines (removed wrappers, flattened hierarchy)

data/.claude/todo/refactor/08-cli-deploy-steps.md

@@ -1,201 +0,0 @@
-# 08 - CLI: Deploy Steps (Details)
-
-## Priority: FIFTH (part of deploy)
-
-Each step is a focused, single-responsibility class.
-
----
-
-## Step 1: provision_network.rb (~50 lines)
-
-**Source:** Extract from `deployer/infrastructure.rb`
-
-**Does:**
-
-- Find or create network
-- Find or create firewall
-
-```ruby
-# cli/deploy/steps/provision_network.rb
-module Nvoi
-  module CLI
-    module Deploy
-      module Steps
-        class ProvisionNetwork
-          def initialize(config, provider, log)
-            @config = config
-            @provider = provider
-            @log = log
-          end
-
-          def run
-            @log.info "Provisioning network: %s", @config.network_name
-            network = @provider.find_or_create_network(@config.network_name)
-
-            @log.info "Provisioning firewall: %s", @config.firewall_name
-            firewall = @provider.find_or_create_firewall(@config.firewall_name)
-
-            { network: network, firewall: firewall }
-          end
-        end
-      end
-    end
-  end
-end
-```
-
----
-
-## Step 2: provision_server.rb (~80 lines)
-
-**Source:** `steps/server_provisioner.rb` + `deployer/infrastructure.rb`
-
-**Does:**
-
-- Create servers for each group
-- Wait for SSH ready
-- Return main server IP
-
----
-
-## Step 3: provision_volume.rb (~150 lines)
-
-**Source:** `steps/volume_provisioner.rb`
-
-**Does:**
-
-- Collect all volumes needed (database, services, app)
-- Create volumes via provider
-- Attach to servers
-- Mount via SSH (format if needed, add to fstab)
-
----
-
-## Step 4: setup_k3s.rb (~400 lines)
-
-**Source:** Merge `steps/k3s_provisioner.rb` + `steps/k3s_cluster_setup.rb`
-
-**Does:**
-
-- Wait for cloud-init
-- Install K3s server on master
-- Setup kubeconfig
-- Setup in-cluster registry
-- Setup NGINX ingress
-- Install K3s agent on workers
-- Label nodes
-- Get cluster token
-
-**Note:** This is the largest step. Consider keeping as single file with private methods, or split into:
-
-- `setup_k3s/master.rb`
-- `setup_k3s/worker.rb`
-- `setup_k3s/registry.rb`
-
----
-
-## Step 5: configure_tunnel.rb (~70 lines)
-
-**Source:** `steps/tunnel_configurator.rb`
-
-**Does:**
-
-- For each app service with domain:
-  - Create/find Cloudflare tunnel
-  - Configure tunnel ingress
-  - Create DNS CNAME record
-- Return array of TunnelInfo
-
----
-
-## Step 6: build_image.rb (~100 lines)
-
-**Source:** `deployer/image_builder.rb` + parts of `remote/docker_manager.rb`
-
-**Does:**
-
-- Build Docker image locally
-- Save to tar
-- Rsync to remote server
-- Import into containerd
-- Tag image
-- Push to in-cluster registry
-
----
-
-## Step 7: deploy_database.rb (~80 lines)
-
-**Source:** `steps/database_provisioner.rb` + `deployer/service_deployer.rb#deploy_database`
-
-**Does:**
-
-- Skip if SQLite (handled by app volumes)
-- Deploy database secret (POSTGRES_USER, etc.)
-- Deploy StatefulSet with hostPath volume
-- Wait for database pod to be Running
-
----
-
-## Step 8: deploy_service.rb (~300 lines)
-
-**Source:** Merge `deployer/orchestrator.rb` + `deployer/service_deployer.rb`
-
-**Does:**
-
-- Deploy app secret (env vars)
-- Deploy additional services (redis, etc.)
-- Deploy app services (web, worker)
-- Deploy cloudflared sidecars
-- Verify traffic routing
-- Run pre-run commands (migrations)
-
-**Note:** Uses `External::Kubectl` for all manifest operations.
-
----
-
-## Step 9: cleanup_images.rb (~40 lines)
-
-**Source:** `deployer/cleaner.rb`
-
-**Does:**
-
-- List all images with prefix
-- Keep newest N images
-- Delete the rest
-
----
-
-## Step Dependencies
-
-```
-provision_network ─┐
-                   ├─► provision_server ─► provision_volume ─► setup_k3s
-                   │
-configure_tunnel ──┼─► build_image ─► deploy_service ─► cleanup_images
-                   │
-                   └── (parallel where possible)
-```
-
----
-
-## Common Patterns Across Steps
-
-### Constructor Signature
-
-All steps follow:
-
-```ruby
-def initialize(config, provider_or_deps, log)
-```
-
-### Return Values
-
-- Most return `nil` (side effects only)
-- Some return data for next step:
-  - `provision_server` → main_server_ip
-  - `configure_tunnel` → [TunnelInfo]
-  - `provision_network` → { network:, firewall: }
-
-### Error Handling
-
-Steps raise specific errors. Command catches and logs.