nvoi 0.1.5 → 0.1.6

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

@@ -0,0 +1,133 @@
+# 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

@@ -0,0 +1,123 @@
+# 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

@@ -0,0 +1,177 @@
+# 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

@@ -0,0 +1,201 @@
+# 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.