nvoi 0.1.5 → 0.1.7

data/.claude/todo/refactor-execution/00-entrypoint.md

@@ -0,0 +1,49 @@
+# Refactor Execution Entrypoint
+
+## Strategy
+
+**Clean slate rebuild.** Not migration.
+
+- **Reference codebase:** `/Users/ben/Desktop/nvoi-rb/` (working code, read-only)
+- **Worktree:** `/Users/ben/Desktop/nvoi-rb-refactor/` (clean slate, write here)
+
+## Setup
+
+```bash
+# Clear worktree lib/nvoi/ (keep exe/, test/, templates/, etc.)
+cd /Users/ben/Desktop/nvoi-rb-refactor
+rm -rf lib/nvoi
+mkdir lib/nvoi
+```
+
+## Execution Order
+
+Each phase: **build → validate → test → commit**
+
+```
+Phase 1: 01-objects.md      → Build objects/ from scratch
+Phase 2: 02-utils.md        → Build utils/ from scratch
+Phase 3: 03-external-cloud.md → Build external/cloud/
+Phase 4: 04-external-dns.md   → Build external/dns/
+Phase 5: 05-external-other.md → Build external/ssh, kubectl, containerd, database
+Phase 6: 06-cli-deploy.md     → Build cli/deploy/
+Phase 7: 07-cli-delete.md     → Build cli/delete/
+Phase 8: 08-cli-exec.md       → Build cli/exec/
+Phase 9: 09-cli-credentials.md → Build cli/credentials/
+Phase 10: 10-cli-db.md        → Build cli/db/
+Phase 11: 11-cli-router.md    → Build cli.rb
+Phase 12: 12-cleanup.md       → Final wiring, lib/nvoi.rb, version.rb
+```
+
+## Per-Phase Protocol
+
+1. **Build** - Create new files reading from reference
+2. **Validate** - User reviews structure
+3. **Test** - `bundle exec rake test`
+4. **Commit** - Only after tests pass
+
+## Current Step
+
+**NOT STARTED**
+
+Next: Clear worktree, then `01-objects.md`

data/.claude/todo/refactor-execution/01-objects.md

@@ -0,0 +1,42 @@
+# 01 - Objects Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create `lib/nvoi/objects/` with:
+
+| File | Content (from reference) |
+|------|--------------------------|
+| `server.rb` | `Server`, `ServerCreateOptions` from `providers/base.rb` |
+| `network.rb` | `Network` from `providers/base.rb` |
+| `firewall.rb` | `Firewall` from `providers/base.rb` |
+| `volume.rb` | `Volume`, `VolumeCreateOptions` from `providers/base.rb`, `MountOptions` from `remote/volume_manager.rb` |
+| `tunnel.rb` | `Tunnel` from `cloudflare/client.rb`, `TunnelInfo` from `deployer/types.rb` |
+| `dns.rb` | `Zone`, `DNSRecord` from `cloudflare/client.rb` |
+| `database.rb` | `DatabaseCredentials`, `DumpOptions`, `RestoreOptions`, `CreateOptions`, `Branch`, `BranchMetadata` from `database/provider.rb` |
+| `service_spec.rb` | `ServiceSpec` from `config/types.rb` |
+
+All under `Nvoi::Objects` namespace.
+
+## Validate
+
+- [ ] `ls lib/nvoi/objects/` shows 8 files
+- [ ] Each file has `module Nvoi::Objects`
+- [ ] Structs match reference
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/objects/server'; p Nvoi::Objects::Server.new(id: '1', name: 'test', status: 'running', public_ipv4: '1.2.3.4')"
+```
+
+(Full test suite runs after all phases complete)
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 1: Build objects/"
+```

data/.claude/todo/refactor-execution/02-utils.md

@@ -0,0 +1,41 @@
+# 02 - Utils Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create `lib/nvoi/utils/` with:
+
+| File | Content (from reference) |
+|------|--------------------------|
+| `logger.rb` | From `logger.rb` |
+| `constants.rb` | From `constants.rb` |
+| `errors.rb` | From `errors.rb` |
+| `namer.rb` | From `config/naming.rb` + add `hostname(subdomain, domain)` |
+| `env_resolver.rb` | From `config/env_resolver.rb` |
+| `config_loader.rb` | Merge `config/loader.rb` + `config/ssh_keys.rb` |
+| `crypto.rb` | Merge `credentials/crypto.rb` + `credentials/manager.rb` |
+| `templates.rb` | Merge `k8s/templates.rb` + `k8s/renderer.rb` |
+| `retry.rb` | From `deployer/retry.rb` |
+
+All under `Nvoi::Utils` namespace.
+
+## Validate
+
+- [ ] `ls lib/nvoi/utils/` shows 9 files
+- [ ] Each file has `module Nvoi::Utils`
+- [ ] `hostname` method added to namer
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/utils/logger'; Nvoi::Utils::Logger.new.info('test')"
+```
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 2: Build utils/"
+```

data/.claude/todo/refactor-execution/03-external-cloud.md

@@ -0,0 +1,38 @@
+# 03 - External Cloud Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create `lib/nvoi/external/cloud/` with:
+
+| File | Content (from reference) |
+|------|--------------------------|
+| `base.rb` | From `providers/base.rb` (interface only, no Structs) |
+| `hetzner.rb` | Merge `providers/hetzner.rb` + `providers/hetzner_client.rb` |
+| `aws.rb` | From `providers/aws.rb` |
+| `scaleway.rb` | Merge `providers/scaleway.rb` + `providers/scaleway_client.rb` |
+| `factory.rb` | From `service/provider.rb` (ProviderHelper → `External::Cloud.for(config)`) |
+
+All under `Nvoi::External::Cloud` namespace.
+Use `Objects::Server`, `Objects::Network`, etc.
+
+## Validate
+
+- [ ] `ls lib/nvoi/external/cloud/` shows 5 files
+- [ ] `base.rb` has no Struct definitions
+- [ ] Each provider uses `Objects::` for return types
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/objects/server'; require './lib/nvoi/external/cloud/base'; p Nvoi::External::Cloud::Base"
+```
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 3: Build external/cloud/"
+```

data/.claude/todo/refactor-execution/04-external-dns.md

@@ -0,0 +1,35 @@
+# 04 - External DNS Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create `lib/nvoi/external/dns/` with:
+
+| File | Content (from reference) |
+|------|--------------------------|
+| `cloudflare.rb` | Merge `cloudflare/client.rb` + `deployer/tunnel_manager.rb` (no Structs) |
+
+Under `Nvoi::External::DNS` namespace.
+Use `Objects::Tunnel`, `Objects::Zone`, `Objects::DNSRecord`, `Objects::TunnelInfo`.
+Add `setup_tunnel` method from TunnelManager.
+
+## Validate
+
+- [ ] `ls lib/nvoi/external/dns/` shows 1 file
+- [ ] No Struct definitions in file
+- [ ] `setup_tunnel` method exists
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/objects/tunnel'; require './lib/nvoi/objects/dns'; require './lib/nvoi/external/dns/cloudflare'; p Nvoi::External::DNS::Cloudflare"
+```
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 4: Build external/dns/"
+```

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

@@ -0,0 +1,46 @@
+# 05 - External Other Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create in `lib/nvoi/external/`:
+
+| File | Content (from reference) |
+|------|--------------------------|
+| `ssh.rb` | From `remote/ssh_executor.rb` |
+| `kubectl.rb` | Extract kubectl ops from `k8s/renderer.rb` |
+| `containerd.rb` | From `remote/docker_manager.rb` (rename class) |
+| `volume_manager.rb` | From `remote/volume_manager.rb` (no MountOptions Struct) |
+
+Create `lib/nvoi/external/database/`:
+
+| File | Content (from reference) |
+|------|--------------------------|
+| `provider.rb` | From `database/provider.rb` (no Structs, use `Objects::`) |
+| `postgres.rb` | From `database/postgres.rb` |
+| `mysql.rb` | From `database/mysql.rb` |
+| `sqlite.rb` | From `database/sqlite.rb` |
+
+Under `Nvoi::External` namespace.
+Use `Objects::MountOptions`, `Objects::DatabaseCredentials`, etc.
+
+## Validate
+
+- [ ] `ls lib/nvoi/external/` shows ssh.rb, kubectl.rb, containerd.rb, volume_manager.rb
+- [ ] `ls lib/nvoi/external/database/` shows 4 files
+- [ ] No Struct definitions in any file
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/external/ssh'; p Nvoi::External::SSH"
+```
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 5: Build external/ssh, kubectl, containerd, database"
+```

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

@@ -0,0 +1,45 @@
+# 06 - CLI Deploy Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create `lib/nvoi/cli/deploy/command.rb`:
+- Orchestrator from `service/deploy.rb`
+- Uses `External::`, `Utils::`, `Objects::`
+
+Create `lib/nvoi/cli/deploy/steps/`:
+
+| File | Content (from reference) |
+|------|--------------------------|
+| `provision_network.rb` | From `deployer/infrastructure.rb` (network + firewall) |
+| `provision_server.rb` | From `steps/server_provisioner.rb` |
+| `provision_volume.rb` | From `steps/volume_provisioner.rb` |
+| `setup_k3s.rb` | Merge `steps/k3s_provisioner.rb` + `steps/k3s_cluster_setup.rb` |
+| `configure_tunnel.rb` | From `steps/tunnel_configurator.rb` |
+| `build_image.rb` | From `deployer/image_builder.rb` |
+| `deploy_database.rb` | From `steps/database_provisioner.rb` |
+| `deploy_service.rb` | Merge `deployer/orchestrator.rb` + `deployer/service_deployer.rb` |
+| `cleanup_images.rb` | From `deployer/cleaner.rb` |
+
+Under `Nvoi::CLI::Deploy` namespace.
+
+## Validate
+
+- [ ] `ls lib/nvoi/cli/deploy/` shows command.rb + steps/
+- [ ] `ls lib/nvoi/cli/deploy/steps/` shows 9 files
+- [ ] command.rb orchestrates steps in correct order
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/cli/deploy/command'; p Nvoi::CLI::Deploy::Command"
+```
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 6: Build cli/deploy/"
+```

data/.claude/todo/refactor-execution/07-cli-delete.md

@@ -0,0 +1,43 @@
+# 07 - CLI Delete Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create `lib/nvoi/cli/delete/command.rb`:
+- Orchestrator from `service/delete.rb`
+- Uses `External::`, `Utils::`, `Objects::`
+
+Create `lib/nvoi/cli/delete/steps/`:
+
+| File | Content (from reference) |
+|------|--------------------------|
+| `detach_volumes.rb` | Extract from `service/delete.rb` |
+| `teardown_server.rb` | Extract from `service/delete.rb` |
+| `teardown_volume.rb` | Extract from `service/delete.rb` |
+| `teardown_firewall.rb` | Extract from `service/delete.rb` |
+| `teardown_network.rb` | Extract from `service/delete.rb` |
+| `teardown_tunnel.rb` | Extract from `service/delete.rb` |
+| `teardown_dns.rb` | Extract from `service/delete.rb` |
+
+Under `Nvoi::CLI::Delete` namespace.
+
+## Validate
+
+- [ ] `ls lib/nvoi/cli/delete/` shows command.rb + steps/
+- [ ] `ls lib/nvoi/cli/delete/steps/` shows 7 files
+- [ ] Teardown order correct: detach → servers → volumes → firewall → network → tunnel → dns
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/cli/delete/command'; p Nvoi::CLI::Delete::Command"
+```
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 7: Build cli/delete/"
+```

data/.claude/todo/refactor-execution/08-cli-exec.md

@@ -0,0 +1,30 @@
+# 08 - CLI Exec Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create `lib/nvoi/cli/exec/command.rb`:
+- From `service/exec.rb`
+- Uses `External::SSH`, `Utils::`
+
+Under `Nvoi::CLI::Exec` namespace.
+
+## Validate
+
+- [ ] `ls lib/nvoi/cli/exec/` shows command.rb
+- [ ] Supports: single server, `--all`, `-i` interactive
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/cli/exec/command'; p Nvoi::CLI::Exec::Command"
+```
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 8: Build cli/exec/"
+```

data/.claude/todo/refactor-execution/09-cli-credentials.md

@@ -0,0 +1,34 @@
+# 09 - CLI Credentials Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create `lib/nvoi/cli/credentials/edit/command.rb`:
+- Edit logic from `credentials/editor.rb`
+- Uses `Utils::Crypto`
+
+Create `lib/nvoi/cli/credentials/show/command.rb`:
+- Show logic from `credentials/editor.rb`
+- Uses `Utils::Crypto`
+
+Under `Nvoi::CLI::Credentials` namespace.
+
+## Validate
+
+- [ ] `ls lib/nvoi/cli/credentials/edit/` shows command.rb
+- [ ] `ls lib/nvoi/cli/credentials/show/` shows command.rb
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/cli/credentials/edit/command'; p Nvoi::CLI::Credentials::Edit::Command"
+```
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 9: Build cli/credentials/"
+```

data/.claude/todo/refactor-execution/10-cli-db.md

@@ -0,0 +1,31 @@
+# 10 - CLI Database Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create `lib/nvoi/cli/db/command.rb`:
+- From `service/db.rb`
+- Uses `External::Database::`, `External::SSH`, `Utils::`
+- Methods: `branch_create`, `branch_list`, `branch_restore`, `branch_download`
+
+Under `Nvoi::CLI::Db` namespace.
+
+## Validate
+
+- [ ] `ls lib/nvoi/cli/db/` shows command.rb
+- [ ] All branch methods present
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/cli/db/command'; p Nvoi::CLI::Db::Command"
+```
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 10: Build cli/db/"
+```

data/.claude/todo/refactor-execution/11-cli-router.md

@@ -0,0 +1,44 @@
+# 11 - CLI Router Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+Create `lib/nvoi/cli.rb`:
+- Thor routing only (~50-80 lines)
+- Lazy requires for each command
+- Delegates to `CLI::Deploy::Command`, `CLI::Delete::Command`, etc.
+
+```ruby
+# Structure
+module Nvoi
+  class CLI < Thor
+    desc "deploy", "Deploy application"
+    def deploy
+      require_relative "cli/deploy/command"
+      CLI::Deploy::Command.new(options).run
+    end
+    # ... etc
+  end
+end
+```
+
+## Validate
+
+- [ ] `wc -l lib/nvoi/cli.rb` < 100 lines
+- [ ] No business logic in cli.rb
+- [ ] All commands delegate to `cli/*/command.rb`
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+ruby -e "require './lib/nvoi/cli'; p Nvoi::CLI"
+```
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 11: Build cli.rb router"
+```

data/.claude/todo/refactor-execution/12-cleanup.md

@@ -0,0 +1,120 @@
+# 12 - Cleanup Execution
+
+## Reference
+Read from: `/Users/ben/Desktop/nvoi-rb/lib/nvoi/`
+
+## Build
+
+### Zeitwerk Pattern (dev-only dependency)
+
+**Gemfile:**
+```ruby
+group :development do
+  gem "zeitwerk"
+end
+```
+
+**lib/nvoi.rb:**
+```ruby
+# frozen_string_literal: true
+
+if defined?(Nvoi::AUTOLOADERS)
+  require "zeitwerk"
+  Nvoi::AUTOLOADERS << Zeitwerk::Loader.for_gem.tap do |loader|
+    loader.ignore("#{__dir__}/nvoi/loader.rb")
+    loader.setup
+  end
+else
+  require_relative "nvoi/loader"
+end
+
+module Nvoi
+  VERSION = "0.1.0"
+end
+```
+
+**bin/generate_loader** (script to regenerate loader.rb):
+```ruby
+#!/usr/bin/env ruby
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.ignore("#{__dir__}/../lib/nvoi/loader.rb")
+
+requires = []
+loader.on_load do |cpath, value, abspath|
+  requires << abspath.sub("#{__dir__}/../lib/", "").sub(".rb", "")
+end
+loader.setup
+loader.eager_load
+
+File.write("#{__dir__}/../lib/nvoi/loader.rb", <<~RUBY)
+  # frozen_string_literal: true
+  # AUTO-GENERATED by bin/generate_loader - do not edit manually
+
+  #{requires.map { |r| "require_relative \"#{r.sub('nvoi/', '')}\"" }.join("\n")}
+RUBY
+
+puts "Generated lib/nvoi/loader.rb with #{requires.size} requires"
+```
+
+**lib/nvoi/loader.rb** (auto-generated, committed):
+```ruby
+# frozen_string_literal: true
+# AUTO-GENERATED by bin/generate_loader - do not edit manually
+
+require_relative "version"
+require_relative "objects/server"
+# ... all files in dependency order
+```
+
+### Create config files
+
+Create `lib/nvoi/version.rb`:
+- From reference
+
+Create `lib/nvoi/config/` (keep config types):
+- `types.rb` - Config classes (Application, ServerConfig, etc.) - use `Objects::ServiceSpec`
+- Other config files as needed
+
+## Validate
+
+- [ ] `tree lib/nvoi -L 2` matches target structure
+- [ ] No old directories: `providers/`, `cloudflare/`, `remote/`, `service/`, `steps/`, `deployer/`, `k8s/`, `database/`, `credentials/`
+- [ ] `ruby bin/generate_loader` runs without error
+- [ ] `lib/nvoi.rb` loads without error (with and without Zeitwerk)
+
+## Test
+
+```bash
+cd /Users/ben/Desktop/nvoi-rb-refactor
+
+# Test with Zeitwerk (dev mode)
+NVOI_AUTOLOADERS=1 ruby -e "module Nvoi; AUTOLOADERS = []; end; require './lib/nvoi'; p Nvoi::Objects::Server"
+
+# Test without Zeitwerk (production mode - uses loader.rb)
+ruby -e "require './lib/nvoi'; p Nvoi::Objects::Server"
+
+# Full test suite
+bundle exec rake test
+```
+
+**Full test suite must pass.**
+
+## Commit
+
+```bash
+git add -A && git commit -m "Phase 12: Final wiring with Zeitwerk pattern"
+```
+
+## Final Verification
+
+```bash
+# CLI smoke test
+./exe/nvoi --help
+./exe/nvoi deploy --help
+./exe/nvoi delete --help
+./exe/nvoi exec --help
+./exe/nvoi credentials --help
+./exe/nvoi db --help
+```