Claude Code transcript

Here's a summary of what it would take to add Vultr support (issue #43):

Current State

The codebase is tightly coupled to DigitalOcean — there's no provider abstraction layer. Every subcommand directly imports and uses python-digitalocean classes (Manager, Droplet, Domain, etc.). The config loader is hardcoded to expect a digital-ocean section.

One bright spot: cloud_config.py is already provider-agnostic since cloud-init is a cross-provider standard.

What Would Need to Change

1. Provider Abstraction Layer (new)

Create a CloudProvider ABC with methods like create_vm(), destroy_vm(), list_vms(), get_ssh_key(), create_dns_record(), etc. Then implement DigitalOceanProvider and VultrProvider.

2. Config (config.py, types.py)

• Support a vultr: section alongside digital-ocean:
• Add provider selection logic
• Map provider-specific parameters (regions, images, sizes all differ between providers)

3. All 9 Subcommands

Every subcommand (create, destroy, list, status, ssh-keys, domains, list-domain, projects, types) currently calls DO APIs directly and would need refactoring to use the provider abstraction.

4. Utilities (util.py)

All helpers (projectFromName, sshKeyFromName, dnsRecordIdFromName) work directly with DO objects and would need provider-neutral equivalents.

5. Tagging/Session System

DO has native tags used for session tracking. Vultr may need an alternative mechanism (metadata, naming conventions).

6. Region/Image/Size Mapping

Hardcoded DO-specific lists in create.py (e.g., ["NYC1", "NYC3", ...], ["ubuntu-22-04-x64", ...]) would need per-provider equivalents.

Vultr Specifics

Vultr is a reasonable choice — it supports cloud-init, has a REST API, offers DNS management, and has similar pricing. The vultr Python library exists. Key differences to handle: - Different auth (API key vs DO access token) - Different resource naming (instances vs droplets, plans vs size slugs) - No native "projects" concept - Different region/image identifiers

Recommended Approach

1. Introduce the provider abstraction first (without Vultr) — refactor all subcommands to go through a CloudProvider interface, with DigitalOceanProvider as the sole implementation
2. Then add VultrProvider as a second implementation
3. Update config to support provider selection

This is a significant refactor (~900 lines of code, all subcommands affected) but the codebase is small enough that it's very manageable.

All 29 tests pass, lint is clean. Here's a summary of what was done:

Changes Made

New files

• machine/provider.py — Abstract base class CloudProvider with provider-neutral data types (VM, SSHKey, DNSRecord). Defines the interface all providers must implement.
• machine/providers/__init__.py — Provider factory (create_provider()) that instantiates the right provider based on config. Maintains KNOWN_PROVIDERS list.
• machine/providers/digitalocean.py — DigitalOceanProvider implementation wrapping all python-digitalocean API calls. All DO-specific logic (region/image validation, project assignment, resource URNs) lives here.

Modified files

• machine/types.py — Config now has provider_name and provider_config instead of access_token. MainCmdCtx now carries a provider instance.
• machine/config.py — Auto-detects provider from config file sections (looks for known provider names like digital-ocean). No longer hardcoded to DO.
• machine/main.py — Creates the provider via factory and passes it through the Click context.
• machine/util.py — Removed all digitalocean imports. Helper functions now work with provider-neutral VM and DNSRecord types.
• machine/cloud_config.py — Takes CloudProvider instead of DO Manager.
• All 8 subcommands — Refactored to use provider from context instead of directly calling digitalocean.*.

Key design decisions

• Backward compatible — Existing digital-ocean: configs work unchanged with auto-detection.
• Provider validates itself — Each provider checks its own required config keys (e.g., DO validates access-token).
• Optional capabilities — list_projects() and assign_to_project() have default no-op implementations in the ABC, since not all providers support projects.
• validate_region()/validate_image() — Default no-ops in ABC; DO provider overrides with its known-valid lists.

To add Vultr (or any other provider), you'd now just need to: 1. Create machine/providers/vultr.py implementing CloudProvider 2. Add "vultr" to KNOWN_PROVIDERS in machine/providers/__init__.py 3. Add the elif branch in create_provider()

The issue is clear: right after droplet.create(), droplet.region is a string (the region slug), not a dict. It only becomes a dict after droplet.load() is called. The original code only accessed droplet.region["slug"] in the list command (after the API returned full objects), never right after creation.

All 6 e2e tests pass. The issue was that droplet.region is a plain string right after droplet.create() but becomes a dict (with a "slug" key) after being fetched from the API via get_all_droplets() or droplet.load(). The fix handles both formats in _droplet_to_vm.

Shall I commit and push this fix?