Claude Code transcript - page 1/2

title:	Add end to end tests
state:	OPEN
author:	dboreham
labels:	
comments:	0
assignees:	
projects:	
milestone:	
number:	35
--
Currently we don't have any tests that verify that the tool can actually create VMs at Digitalocean with associated DNS.
It should be reasonably straightforward to add such tests, provided there is a test digitalocean environment made available, test DNS zone and so on.
These tests would need to be runnable separately from the existing tests because for cost and run time reasons it wouldn't be reasonable to run them on every commit.

Excellent! Now I have all the information I need. Let me create a comprehensive summary report of my findings.

---

## CODEBASE EXPLORATION SUMMARY

I've thoroughly explored the machine CLI codebase. Here's my comprehensive analysis:

### 1. EXISTING TEST SETUP

**Test Files:**
- `/home/david/projects/stirlingbridge/machine/tests/test_cli_integration.py` - Integration tests running CLI as subprocess
- `/home/david/projects/stirlingbridge/machine/tests/test_input_validation.py` - Input validation tests
- `/home/david/projects/stirlingbridge/machine/tests/test_config.py` - Config expansion tests
- `/home/david/projects/stirlingbridge/machine/tests/__init__.py` - Empty init file

**Test Infrastructure:**
- **Framework:** pytest (in dev dependencies)
- **Test command:** `uv run pytest tests/ -v` (also in Makefile as `make test`)
- **CI/CD:** GitHub Actions workflow `.github/workflows/test.yml` runs tests on push and PR to main
- **No pytest.ini:** Uses default pytest discovery (tests/ directory)
- **Test patterns:**
  - `run_machine(*args, env_override=None)` - Helper that runs CLI as subprocess via `uv run machine`
  - `write_config(path, content)` - Helper that writes YAML config to files
  - Tests use `tmp_path` pytest fixture for temporary config files
  - Tests check stdout/stderr and return codes

**Existing Test Coverage:**
- Version command smoke tests
- Environment variable expansion in config (${VAR} syntax)
- Invalid machine type error handling
- Missing config section validation
- Missing required config keys validation
- --no-initialize flag edge cases (no traceback on missing user_data)

### 2. VM CREATION FLOW (CREATE SUBCOMMAND)

**File:** `/home/david/projects/stirlingbridge/machine/machine/subcommands/create.py`

**Complete Flow:**
1. **Load context & config** from CLI options
2. **Validate inputs:**
   - Region validation against hardcoded list: `NYC1`, `NYC3`, `AMS3`, `SFO2`, `SFO3`, `SGP1`, `LON1`, `FRA1`, `TOR1`, `BLR1`, `SYD1`
   - Image validation (warning only for unknown images)
   - DNS zone check if `--update-dns` requested
3. **Get SSH key** from DigitalOcean (by name) - required for droplet creation
4. **Generate cloud-init user-data** (if `--initialize` flag set):
   - Calls `get_user_data()` from cloud_config.py
   - Creates non-root user with sudo access
   - Installs SSH public key
   - Optionally downloads and runs initialization script
5. **Create droplet** via python-digitalocean API:
   - Name, region, image, size_slug from config or CLI overrides
   - SSH key and user-data
   - Tags: session ID, machine:created, machine:type:*, custom tags
   - `backups=False`
6. **Assign to project** (if configured):
   - Looks up project by name
   - Assigns droplet resource to project
7. **Wait for IP address** (if `--wait-for-ip` or `--update-dns`):
   - Polls droplet.load() every 1 second until ip_address assigned
8. **Create DNS record** (if `--update-dns` and ip_address obtained):
   - Creates A record in dns_zone: `name.<zone>`
   - TTL: 5 minutes (300 seconds)
   - Record tag: `machine:created`

**CLI Options:**
- `--name` (required): Droplet name
- `--type` (required if `--initialize`): Machine type from config
- `--tag`: Custom tag to add
- `--region`: Override config default
- `--machine-size` / `--image`: Override config defaults
- `--wait-for-ip`: Wait for IP assignment
- `--update-dns` (default=True): Create DNS record
- `--initialize` (default=True): Use cloud-init user-data

### 3. CLOUD CONFIG GENERATION

**File:** `/home/david/projects/stirlingbridge/machine/machine/cloud_config.py`

**Function:** `get_user_data(manager, ssh_key_name, fqdn, machine_config) -> str`

**Output:** cloud-config YAML user-data for cloud-init

**Structure:**
```
users:
  - name: <new_user_name>
    groups: sudo
    shell: /bin/bash
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    ssh-authorized-keys:
      - <ssh_public_key>

runcmd: (optional, if script_url && script_dir && script_path)
  - mkdir -p <script_dir>
  - curl -L <script_url> -o <script_path>
  - chmod +x <script_path>
  - [su, -c, "env MACHINE_SCRIPT_URL=... MACHINE_SCRIPT_DIR=... MACHINE_FQDN=... <script_path> <script_args>", -, <new_user_name>]
```

**Available Variables (in script-args):**
- `$MACHINE_SCRIPT_URL` - Script URL
- `$MACHINE_SCRIPT_DIR` - Script directory
- `$MACHINE_FQDN` - FQDN (e.g., myvm.example.com)

**Notes:**
- Script runs as the new user (via `su`)
- Arguments expanded with environment variables before escaping
- Quotes in script-args escaped properly

### 4. CONFIG FILE FORMAT

**Path:** `~/.machine/config.yml` (or override with `--config-file`)

**File:** `/home/david/projects/stirlingbridge/machine/machine/config.py`

**Structure:**
```yaml
digital-ocean:
  access-token: <string>          # Required
  ssh-key: <string>               # Required - SSH key name
  dns-zone: <string>              # Optional - for DNS operations
  machine-size: <string>          # Required - e.g., s-1vcpu-1gb
  image: <string>                 # Required - e.g., ubuntu-22-04-x64
  region: <string>                # Required - e.g., nyc1
  project: <string>               # Optional - DO project name

machines:
  <type-name>:                     # Any custom name
    new-user-name: <string>        # Required
    script-url: <string>           # Optional
    script-dir: <string>           # Optional
    script-path: <string>          # Optional
    script-args: <string>          # Optional
```

**Config Data Classes:**
- `Config` (dataclass): `access_token`, `ssh_key`, `dns_zone`, `machine_size`, `image`, `region`, `project`
- `MachineConfig` (dataclass): `new_user_name`, `script_url`, `script_dir`, `script_path`, `script_args`

**Environment Variable Expansion:**
- Syntax: `${VAR}` or `${VAR:-default}`
- Applied recursively to all config values (strings, dicts, lists)
- Works in both digital-ocean and machines sections
- Missing var without default = fatal error
- Uses regex pattern: `\$\{([^}]+)\}`
- Handles `:-` syntax for defaults

**Validation:**
- `digital-ocean` section required
- `access-token`, `ssh-key`, `machine-size`, `image`, `region` required in digital-ocean
- `machines` section required for create command
- Each machine must have `new-user-name`
- All script-related fields optional but must all be present or all absent for cloud-init script

### 5. DESTROY FLOW

**File:** `/home/david/projects/stirlingbridge/machine/machine/subcommands/destroy.py`

**For Each Droplet:**
1. **Get droplet** by ID from DigitalOcean
2. **Safety checks** (unless `--all`):
   - Must have `machine:created` tag
   - Must have session ID tag matching current session
3. **Confirmation** (default=True):
   - Requires exact typing of "YES" (not "y" or "yes")
   - Skip with `--no-confirm`
4. **Destroy droplet** via python-digitalocean API
5. **Delete DNS record** (if `--delete-dns` and dns_zone configured):
   - Looks up record by name
   - Deletes by record ID

**CLI Options:**
- `--confirm` (default=True): Require user confirmation
- `--delete-dns` (default=True): Remove associated DNS records
- `--all`: Skip safety checks (destroy even non-machine-created droplets)
- Positional: One or more droplet IDs

### 6. LIST & STATUS COMMANDS

**List Command** (`/home/david/projects/stirlingbridge/machine/machine/subcommands/list.py`):
- **Filter options:** `--id`, `--name`, `--tag`, `--type`, `--region`, `--all`
- **Output formats:** default, `--quiet`, `--output json`
- **Default filtering:** Current session only (unless `--all`)
- **Filtering logic:** API call with session tag, then client-side filtering for other fields
- **Output:** `name (id, region, type): ip_address` or JSON with id, name, tags, region, ip, type
- **Unique check:** `--unique` flag errors if >1 match

**Status Command** (`/home/david/projects/stirlingbridge/machine/machine/subcommands/status.py`):
- **Same filtering** as list command
- **Additional query:** HTTP GET to `http://<ip>:4242/cgi-bin/<status-check>` (default: cloud-init-status)
- **Expected response:** JSON with `{"status": "..."}`
- **Status output:** droplet-status + custom status-check result or "UNKNOWN"
- **Output formats:** default table or JSON

**List Domain** (`/home/david/projects/stirlingbridge/machine/machine/subcommands/list_domain.py`):
- **Zone argument:** Required or from config
- **Filter options:** `--name`, `--type` (default A and AAAA), `--all`
- **Output formats:** default, `--quiet`, `--output json`
- **Default filtering:** Session-based (only records matching session's droplet IPs)
- **Output:** `name\ttype\tdata` or JSON

**Other List Commands:**
- `domains.py` - List all DNS zones
- `ssh_keys.py` - List SSH keys: `id: name (fingerprint)`
- `projects.py` - List DigitalOcean projects
- `types.py` - List configured machine types from config file

### 7. TAGGING & SESSION MANAGEMENT

**Tags applied to droplets:**
- `machine:created` - Identifies machine created by this tool
- `machine:session:<session-id>` - 8-char UUID hex session ID
- `machine:type:<machine-type>` - Lower-cased machine type name
- Custom tags from `--tag` flag

**Session ID:**
- Auto-generated: 8-char random UUID (hex only)
- Stored in: `~/.machine/session-id.yml`
- File format: `id: <session-id>`
- Can be overridden with global `--session-id` option
- Persists across invocations

**Filtering by Session:**
- Most commands default to current session only
- `--all` flag includes machines from all sessions or not created by tool

### 8. UTILITY FUNCTIONS

**File:** `/home/david/projects/stirlingbridge/machine/machine/util.py`

**Key Functions:**
- `projectFromName(manager, name) -> Project` - Find project by name
- `sshKeyFromName(manager, name) -> SSHKey` - Find SSH key by name
- `dnsRecordIdFromName(domain, name) -> str` - Find DNS record ID by name
- `get_machine_type(droplet) -> str` - Extract machine type from tags
- `is_machine_created(droplet) -> bool` - Check for machine:created tag
- `is_same_session(command_context, droplet) -> bool` - Check session ID tag match
- `load_session_id() -> str` - Load or generate session ID
- `droplet_to_json_obj(droplet) -> dict` - Convert droplet to JSON-serializable dict
- `dns_record_to_json_obj(dns_record, zone, droplet) -> dict` - Convert DNS record to JSON

### 9. DEPENDENCY INJECTION & GLOBALS

**File:** `/home/david/projects/stirlingbridge/machine/machine/di.py`

**Simple pattern:** Class `d` with class variable `opt: CliOptions`
- Set in main.py once at startup
- Used throughout for debug/quiet/verbose/dry-run flags
- Note: `--dry-run` flag set but never used in actual implementation

### 10. ARCHITECTURE & KEY INSIGHTS

**CLI Framework:** Click 8.1.7
- Context object carries `MainCmdCtx` with config and session_id
- Global `d.opt` for CLI options
- Commands organized in subcommands/ directory

**Config Loading:**
- Lazy loaded first time needed
- Cached in `_loaded_config.c` class variable
- Environment variable expansion applied on load

**Error Handling:**
- `fatal_error()` prints to stderr and exits(1)
- Input validation prevents tracebacks (graceful error messages)
- Missing config sections caught early

**Cloud Provider Integration:**
- python-digitalocean 1.17.0 library
- Direct API calls, no abstraction layer
- Polling for IP address (1-second intervals)
- Exceptions caught for DNS operations (NotFoundError)

**DNS Integration:**
- Optional feature (controlled by `dns_zone` config + `--update-dns` flag)
- Uses DigitalOcean Domain API
- A records with 5-minute TTL
- Records tagged with `machine:created` for tracking
- Deletion on droplet destroy

### 11. END-TO-END TEST PLANNING CONSIDERATIONS

For real DigitalOcean integration tests:

1. **Test Fixtures Needed:**
   - Real DO API token (env var)
   - Real SSH key name in DO account
   - Real DNS zone (optional)
   - Real DO project (optional)

2. **Droplet Lifecycle:**
   - Create waits for IP (1-second polls)
   - DNS record takes time to propagate
   - Droplet teardown is instant (no waiting)

3. **Idempotency Challenges:**
   - Droplet names must be unique
   - DNS records must be cleaned up
   - Use session IDs or timestamps to avoid conflicts

4. **Test Isolation:**
   - Each test should use unique droplet/DNS names
   - Use session override to group test droplets
   - Ensure cleanup (even on test failure)

5. **Async Considerations:**
   - IP assignment can take 5-10 seconds
   - DNS propagation variable
   - Cloud-init script execution time variable

6. **Safety:**
   - Confirm destroy requires "YES" (not automatable)
   - Can use `--no-confirm` in tests
   - Session-based filtering provides safety isolation

7. **Validation Points:**
   - Droplet exists with correct name/tags
   - IP address assigned
   - DNS record created with correct values
   - Cloud-init executed (script output, user created)
   - Droplet destroyed
   - DNS record deleted

---

**Key File Locations:**
- Entry point: `/home/david/projects/stirlingbridge/machine/machine/main.py`
- Create command: `/home/david/projects/stirlingbridge/machine/machine/subcommands/create.py`
- Destroy command: `/home/david/projects/stirlingbridge/machine/machine/subcommands/destroy.py`
- Config parsing: `/home/david/projects/stirlingbridge/machine/machine/config.py`
- Cloud-init generation: `/home/david/projects/stirlingbridge/machine/machine/cloud_config.py`
- Utilities: `/home/david/projects/stirlingbridge/machine/machine/util.py`
- Test directory: `/home/david/projects/stirlingbridge/machine/tests/`
- Type definitions: `/home/david/projects/stirlingbridge/machine/machine/types.py`

agentId: a42a54498e70cd939 (for resuming to continue this agent's work if needed)
<usage>total_tokens: 47674
tool_uses: 38
duration_ms: 70899</usage>

     1→"""Integration tests that run the machine CLI as a subprocess, the same way a user would."""
     2→
     3→import os
     4→import subprocess
     5→import textwrap
     6→import pytest
     7→
     8→
     9→def run_machine(*args, env_override=None):
    10→    """Run the machine CLI as a subprocess and return the result."""
    11→    env = os.environ.copy()
    12→    if env_override:
    13→        env.update(env_override)
    14→    result = subprocess.run(
    15→        ["uv", "run", "machine"] + list(args),
    16→        capture_output=True,
    17→        text=True,
    18→        env=env,
    19→    )
    20→    return result
    21→
    22→
    23→def write_config(path, content):
    24→    with open(path, "w") as f:
    25→        f.write(textwrap.dedent(content))
    26→
    27→
    28→class TestVersionCommand:
    29→    """Smoke test: the CLI runs and the version command works without any config."""
    30→
    31→    def test_version_runs(self):
    32→        result = run_machine("version")
    33→        assert result.returncode == 0
    34→        assert result.stdout.strip()  # prints something
    35→
    36→    def test_help_runs(self):
    37→        result = run_machine("--help")
    38→        assert result.returncode == 0
    39→        assert "Usage" in result.stdout
    40→
    41→
    42→class TestEnvVarExpansionIntegration:
    43→    """End-to-end tests that verify environment variable expansion works
    44→    when the actual machine tool is invoked with a config file."""
    45→
    46→    @pytest.fixture()
    47→    def config_dir(self, tmp_path):
    48→        return tmp_path
    49→
    50→    def test_env_var_expanded_in_config(self, config_dir):
    51→        config_file = config_dir / "config.yml"
    52→        write_config(
    53→            config_file,
    54→            """\
    55→            digital-ocean:
    56→              access-token: "${TEST_DO_TOKEN}"
    57→              ssh-key: test-key
    58→              machine-size: s-1vcpu-1gb
    59→              image: ubuntu-22-04-x64
    60→              region: nyc1
    61→              project: test-project
    62→            machines:
    63→              test-machine:
    64→                new-user-name: testuser
    65→            """,
    66→        )
    67→        result = run_machine(
    68→            "--debug",
    69→            "--config-file",
    70→            str(config_file),
    71→            "types",
    72→            env_override={"TEST_DO_TOKEN": "tok_secret_12345"},
    73→        )
    74→        assert result.returncode == 0
    75→        # The debug output on stderr should contain the expanded token value
    76→        assert "tok_secret_12345" in result.stderr
    77→        # And should NOT contain the unexpanded variable reference
    78→        assert "${TEST_DO_TOKEN}" not in result.stderr
    79→        # The types command should list the machine name on stdout
    80→        assert "test-machine" in result.stdout
    81→
    82→    def test_multiple_env_vars_expanded(self, config_dir):
    83→        config_file = config_dir / "config.yml"
    84→        write_config(
    85→            config_file,
    86→            """\
    87→            digital-ocean:
    88→              access-token: "${TEST_TOKEN}"
    89→              ssh-key: "${TEST_SSH_KEY}"
    90→              machine-size: s-1vcpu-1gb
    91→              image: ubuntu-22-04-x64
    92→              region: nyc1
    93→              project: test-project
    94→            machines:
    95→              dev:
    96→                new-user-name: devuser
    97→            """,
    98→        )
    99→        result = run_machine(
   100→            "--debug",
   101→            "--config-file",
   102→            str(config_file),
   103→            "types",
   104→            env_override={"TEST_TOKEN": "expanded_token", "TEST_SSH_KEY": "expanded_key"},
   105→        )
   106→        assert result.returncode == 0
   107→        assert "expanded_token" in result.stderr
   108→        assert "expanded_key" in result.stderr
   109→
   110→    def test_env_var_with_default_uses_default_when_unset(self, config_dir):
   111→        config_file = config_dir / "config.yml"
   112→        write_config(
   113→            config_file,
   114→            """\
   115→            digital-ocean:
   116→              access-token: fake-token
   117→              ssh-key: test-key
   118→              machine-size: "${TEST_SIZE:-s-2vcpu-4gb}"
   119→              image: ubuntu-22-04-x64
   120→              region: nyc1
   121→              project: test-project
   122→            machines:
   123→              myvm:
   124→                new-user-name: admin
   125→            """,
   126→        )
   127→        # Make sure TEST_SIZE is not in the environment
   128→        clean_env = os.environ.copy()
   129→        clean_env.pop("TEST_SIZE", None)
   130→        result = run_machine(
   131→            "--debug",
   132→            "--config-file",
   133→            str(config_file),
   134→            "types",
   135→            env_override={},
   136→        )
   137→        # Run with TEST_SIZE explicitly removed
   138→        result = subprocess.run(
   139→            ["uv", "run", "machine", "--debug", "--config-file", str(config_file), "types"],
   140→            capture_output=True,
   141→            text=True,
   142→            env=clean_env,
   143→        )
   144→        assert result.returncode == 0
   145→        assert "s-2vcpu-4gb" in result.stderr
   146→
   147→    def test_env_var_with_default_uses_value_when_set(self, config_dir):
   148→        config_file = config_dir / "config.yml"
   149→        write_config(
   150→            config_file,
   151→            """\
   152→            digital-ocean:
   153→              access-token: fake-token
   154→              ssh-key: test-key
   155→              machine-size: "${TEST_SIZE:-s-2vcpu-4gb}"
   156→              image: ubuntu-22-04-x64
   157→              region: nyc1
   158→              project: test-project
   159→            machines:
   160→              myvm:
   161→                new-user-name: admin
   162→            """,
   163→        )
   164→        result = run_machine(
   165→            "--debug",
   166→            "--config-file",
   167→            str(config_file),
   168→            "types",
   169→            env_override={"TEST_SIZE": "s-4vcpu-8gb"},
   170→        )
   171→        assert result.returncode == 0
   172→        assert "s-4vcpu-8gb" in result.stderr
   173→        assert "s-2vcpu-4gb" not in result.stderr
   174→
   175→    def test_missing_env_var_without_default_exits_with_error(self, config_dir):
   176→        config_file = config_dir / "config.yml"
   177→        write_config(
   178→            config_file,
   179→            """\
   180→            digital-ocean:
   181→              access-token: "${DEFINITELY_NOT_SET_VAR}"
   182→              ssh-key: test-key
   183→              machine-size: s-1vcpu-1gb
   184→              image: ubuntu-22-04-x64
   185→              region: nyc1
   186→              project: test-project
   187→            machines:
   188→              myvm:
   189→                new-user-name: admin
   190→            """,
   191→        )
   192→        clean_env = os.environ.copy()
   193→        clean_env.pop("DEFINITELY_NOT_SET_VAR", None)
   194→        result = subprocess.run(
   195→            ["uv", "run", "machine", "--config-file", str(config_file), "types"],
   196→            capture_output=True,
   197→            text=True,
   198→            env=clean_env,
   199→        )
   200→        assert result.returncode != 0
   201→        assert "DEFINITELY_NOT_SET_VAR" in result.stderr
   202→
   203→    def test_env_var_in_machine_config_section(self, config_dir):
   204→        config_file = config_dir / "config.yml"
   205→        write_config(
   206→            config_file,
   207→            """\
   208→            digital-ocean:
   209→              access-token: fake-token
   210→              ssh-key: test-key
   211→              machine-size: s-1vcpu-1gb
   212→              image: ubuntu-22-04-x64
   213→              region: nyc1
   214→              project: test-project
   215→            machines:
   216→              web-server:
   217→                new-user-name: "${TEST_USERNAME}"
   218→              db-server:
   219→                new-user-name: admin
   220→            """,
   221→        )
   222→        result = run_machine(
   223→            "--debug",
   224→            "--config-file",
   225→            str(config_file),
   226→            "types",
   227→            env_override={"TEST_USERNAME": "deploy_user"},
   228→        )
   229→        assert result.returncode == 0
   230→        assert "deploy_user" in result.stderr
   231→        # Both machine types should be listed
   232→        assert "db-server" in result.stdout
   233→        assert "web-server" in result.stdout
   234→

     1→# Setup dev environment
     2→dev:
     3→	uv sync
     4→
     5→build:
     6→	./sh/build-package.sh
     7→
     8→test:
     9→	uv run pytest tests/ -v
    10→
    11→lint:
    12→	uv run flake8
    13→

     1→[project]
     2→name = "machine"
     3→version = "1.0.0"
     4→description = "Utility for creating and managing VMs"
     5→readme = "README.md"
     6→license = "AGPL-3.0-only"
     7→requires-python = ">=3.8"
     8→authors = [
     9→    { name = "Stirlingbridge", email = "info@stirlingbridge.website" },
    10→]
    11→classifiers = [
    12→    "Programming Language :: Python :: 3.8",
    13→    "Operating System :: OS Independent",
    14→]
    15→dependencies = [
    16→    "click==8.1.7",
    17→    "python-digitalocean==1.17.0",
    18→    "ruamel.yaml>=0.17.32",
    19→    "requests==2.32.3",
    20→    "expandvars==1.0.0",
    21→]
    22→
    23→[project.scripts]
    24→machine = "machine.main:main"
    25→
    26→[project.urls]
    27→Homepage = "https://github.com/stirlingbridge/machine"
    28→
    29→[build-system]
    30→requires = ["hatchling"]
    31→build-backend = "hatchling.build"
    32→
    33→[dependency-groups]
    34→dev = [
    35→    "flake8",
    36→    "black",
    37→    "pytest",
    38→]
    39→

     1→import click
     2→import digitalocean
     3→import time
     4→from machine.config import get_machine
     5→from machine.di import d
     6→from machine.log import fatal_error, info, debug, output
     7→from machine.types import MainCmdCtx, TAG_MACHINE_CREATED, TAG_MACHINE_TYPE_PREFIX
     8→from machine.util import projectFromName, sshKeyFromName
     9→from machine.cloud_config import get_user_data
    10→
    11→from machine.types import TAG_MACHINE_SESSION_PREFIX
    12→
    13→
    14→def _validate_region(region: str):
    15→    valid_regions = ["NYC1", "NYC3", "AMS3", "SFO2", "SFO3", "SGP1", "LON1", "FRA1", "TOR1", "BLR1", "SYD1"]
    16→    if region is not None and region.upper() not in valid_regions:
    17→        fatal_error(f"Error: region {region} is not one of {valid_regions}")
    18→
    19→
    20→def _validate_image(image: str):
    21→    valid_images = [
    22→        "almalinux-8-x64",
    23→        "almalinux-9-x64",
    24→        "centos-stream-9-x64",
    25→        "debian-11-x64",
    26→        "debian-12-x64",
    27→        "fedora-39-x64",
    28→        "fedora-40-x64",
    29→        "rockylinux-9-x64",
    30→        "rockylinux-8-x64",
    31→        "ubuntu-20-04-x64",
    32→        "ubuntu-22-04-x64",
    33→        "ubuntu-24-04-x64",
    34→    ]
    35→    if image is not None and image not in valid_images:
    36→        info(f"Warning: image {image} is not one of these known valid images: {valid_images}")
    37→
    38→
    39→@click.command(help="Create a machine")
    40→@click.option("--name", "-n", required=True, metavar="<MACHINE-NAME>", help="Name for new machine")
    41→@click.option("--tag", "-t", metavar="<TAG-TEXT>", help="tag to be applied to new machine")
    42→@click.option("--type", "-m", metavar="<MACHINE-TYPE>", help="create a machine of this type")
    43→@click.option("--region", "-r", metavar="<REGION-CODE>", help="create a machine in this region (overrides default from config)")
    44→@click.option(
    45→    "--machine-size", "-s", metavar="<MACHINE-SLUG>", help="create a machine of this size (overrides default from config)"
    46→)
    47→@click.option("--image", "-s", metavar="<IMAGE-NAME>", help="create a machine from this image (overrides default from config)")
    48→@click.option("--wait-for-ip/--no-wait-for-up", default=False)
    49→@click.option("--update-dns/--no-update-dns", default=True)
    50→@click.option("--initialize/--no-initialize", default=True)
    51→@click.pass_context
    52→def command(context, name, tag, type, region, machine_size, image, wait_for_ip, update_dns, initialize):
    53→    command_context: MainCmdCtx = context.obj
    54→    config = command_context.config
    55→
    56→    if update_dns and not config.dns_zone:
    57→        fatal_error("Error: DNS update requested but no zone configured")
    58→
    59→    manager = digitalocean.Manager(token=command_context.config.access_token)
    60→
    61→    user_data = None
    62→    if initialize:
    63→        if not type:
    64→            fatal_error("Error: a machine type must be supplied")
    65→        machine_config = get_machine(type)
    66→        if not machine_config:
    67→            fatal_error(f"Error: machine type {type} is not defined")
    68→        fqdn = f"{name}.{config.dns_zone}" if config.dns_zone else None
    69→        user_data = get_user_data(manager, config.ssh_key, fqdn, machine_config)
    70→        if d.opt.debug:
    71→            info("user-data is:")
    72→            info(user_data)
    73→
    74→    ssh_key = sshKeyFromName(manager, config.ssh_key)
    75→    if not ssh_key:
    76→        fatal_error(f"Error: SSH key '{config.ssh_key}' not found in DigitalOcean")
    77→
    78→    _validate_region(region)
    79→    _validate_image(image)
    80→
    81→    tags = [
    82→        TAG_MACHINE_SESSION_PREFIX + command_context.session_id,
    83→        TAG_MACHINE_CREATED,
    84→    ]
    85→    if type:
    86→        tags.append(TAG_MACHINE_TYPE_PREFIX + type.lower())
    87→    if tag:
    88→        tags.append(tag)
    89→
    90→    droplet = digitalocean.Droplet(
    91→        token=config.access_token,
    92→        name=name,
    93→        region=region if region is not None else config.region,
    94→        image=image if image is not None else config.image,
    95→        size_slug=machine_size if machine_size is not None else config.machine_size,
    96→        ssh_keys=[ssh_key],
    97→        tags=tags,
    98→        user_data=user_data,
    99→        backups=False,
   100→    )
   101→    # Create the droplet
   102→    # This call returns nothing, it modifies the droplet object
   103→    droplet.create()
   104→    if droplet.id:
   105→        if d.opt.quiet:
   106→            output(f"{droplet.id}")
   107→        else:
   108→            output(f"New droplet created with id: {droplet.id}")
   109→    # If requested, assign to a specified project
   110→    if config.project:
   111→        project_name = config.project
   112→        project = projectFromName(manager, project_name)
   113→        if not project:
   114→            fatal_error(f"Error: Project {project_name} does not exist, machine created but not assigned to project")
   115→        project.assign_resource([f"do:droplet:{droplet.id}"])
   116→        if d.opt.verbose:
   117→            info(f"Assigned droplet to project: {project}")
   118→    # If requested, or if we are going to set a DNS record get the droplet's IPv4 address
   119→    if wait_for_ip or update_dns:
   120→        ip_address = None
   121→        while not ip_address:
   122→            time.sleep(1)
   123→            droplet.load()
   124→            ip_address = droplet.ip_address
   125→            if d.opt.verbose:
   126→                output("Waiting for droplet IP address")
   127→        if d.opt.quiet:
   128→            info(f"{ip_address}")
   129→        else:
   130→            info(f"IP Address: {ip_address}")
   131→    # If requested, and we have the IP address, create a DNS host record for the droplet
   132→    if update_dns and ip_address and config.dns_zone:
   133→        zone = config.dns_zone
   134→        host = name
   135→        if d.opt.debug:
   136→            debug(f"Setting host record {host}.{zone} to {ip_address}")
   137→        domain = digitalocean.Domain(token=config.access_token, name=zone)
   138→        try:
   139→            record = domain.create_new_domain_record(type="A", ttl=60 * 5, name=host, data=ip_address, tag=TAG_MACHINE_CREATED)
   140→        except digitalocean.NotFoundError:
   141→            info(f"Warning: DNS zone '{zone}' not found in DigitalOcean, DNS record not set")
   142→            record = None
   143→        if record:
   144→            if d.opt.verbose:
   145→                info(f"Created DNS record:{record}")
   146→            if not d.opt.quiet:
   147→                info(f"DNS: {host}.{zone}")
   148→

     1→import click
     2→import digitalocean
     3→
     4→from machine.di import d
     5→from machine.log import debug, fatal_error, output
     6→from machine.util import dnsRecordIdFromName, is_machine_created
     7→from machine.types import MainCmdCtx
     8→
     9→from machine.util import is_same_session
    10→
    11→
    12→@click.command(help="Destroy one or more machines")
    13→@click.option("--confirm/--no-confirm", default=True)
    14→@click.option("--delete-dns/--no-delete-dns", default=True)
    15→@click.option(
    16→    "--all",
    17→    is_flag=True,
    18→    default=False,
    19→    help="Include machines not created by this tool",
    20→)
    21→@click.argument("droplet-ids", nargs=-1)
    22→@click.pass_context
    23→def command(context, confirm, delete_dns, all, droplet_ids):
    24→    command_context: MainCmdCtx = context.obj
    25→    config = command_context.config
    26→    manager = digitalocean.Manager(token=config.access_token)
    27→    for droplet_id in droplet_ids:
    28→        try:
    29→            droplet = manager.get_droplet(droplet_id)
    30→        except digitalocean.NotFoundError:
    31→            fatal_error(f"Error: machine with id {droplet_id} not found")
    32→        name = droplet.name
    33→
    34→        if not is_machine_created(droplet) and not all:
    35→            fatal_error(f'ERROR: Cannot destroy droplet "{name}" (id: {droplet.id}), it was not created by machine.')
    36→
    37→        if not is_same_session(command_context, droplet) and not all:
    38→            fatal_error(
    39→                f'ERROR: Cannot destroy droplet "{name}" (id: {droplet.id}), it was created by a different session of machine.'
    40→            )
    41→
    42→        if confirm:
    43→            output(
    44→                "Type YES (not y or yes or Yes) to confirm that you want to permanently"
    45→                f' DELETE/DESTROY droplet "{name}" (id: {droplet.id})'
    46→            )
    47→            confirmation = input()
    48→            if confirmation != "YES":
    49→                fatal_error("Destroy operation aborted, not confirmed by user")
    50→        result = droplet.destroy()
    51→
    52→        if result and delete_dns and config.dns_zone:
    53→            zone = config.dns_zone
    54→            if d.opt.debug:
    55→                debug(f"Deleting host record {name}.{zone}")
    56→            domain = digitalocean.Domain(token=config.access_token, name=zone)
    57→            if not domain:
    58→                fatal_error(f"Error: Domain {domain} does not exist, machine destroyed but DNS record not removed")
    59→            record_id = dnsRecordIdFromName(domain, name)
    60→            if record_id:
    61→                if d.opt.debug:
    62→                    debug(f"Deleting dns record id={record_id}")
    63→                domain.delete_domain_record(id=record_id)
    64→            else:
    65→                if d.opt.debug:
    66→                    debug(f"No dns record found for {name}.{zone}")
    67→
    68→        if not result:
    69→            fatal_error("Error destroying machine")
    70→

     1→import click
     2→import json
     3→import digitalocean
     4→
     5→from machine.log import fatal_error, output
     6→from machine.types import MainCmdCtx, TAG_MACHINE_TYPE_PREFIX, TAG_MACHINE_SESSION_PREFIX
     7→from machine.util import get_machine_type, is_machine_created, is_same_session, droplet_to_json_obj
     8→
     9→
    10→def print_normal(droplets):
    11→    for droplet in droplets:
    12→        region = droplet.region["slug"] if droplet.region else "unknown"
    13→        output(f"{droplet.name} ({droplet.id}, {region}, {get_machine_type(droplet)}): {droplet.ip_address}")
    14→
    15→
    16→def print_quiet(droplets):
    17→    for droplet in droplets:
    18→        output(droplet.id)
    19→
    20→
    21→def print_json(droplets):
    22→    output(json.dumps([droplet_to_json_obj(d) for d in droplets]))
    23→
    24→
    25→def get_droplets(command_context, id=None, name=None, tag=None, type=None, region=None, all=False):
    26→    manager = digitalocean.Manager(token=command_context.config.access_token)
    27→    droplets = []
    28→    if id:
    29→        droplet = manager.get_droplet(id)
    30→        if droplet:
    31→            droplets.append(droplet)
    32→
    33→    if all:
    34→        droplets = manager.get_all_droplets()
    35→    else:
    36→        droplets = manager.get_all_droplets(tag_name=TAG_MACHINE_SESSION_PREFIX + command_context.session_id)
    37→
    38→    # we can't combine most filters over the API, so we also filter ourselves
    39→    if name:
    40→        droplets = filter(lambda d: d.name == name, droplets)
    41→
    42→    if tag:
    43→        droplets = filter(lambda d: tag in d.tags, droplets)
    44→
    45→    if type:
    46→        droplets = filter(lambda d: TAG_MACHINE_TYPE_PREFIX + type.lower() in d.tags, droplets)
    47→
    48→    if region:
    49→        droplets = filter(lambda d: d.region and region == d.region["slug"], droplets)
    50→
    51→    if not all:
    52→        droplets = filter(lambda d: is_machine_created(d) and is_same_session(command_context, d), droplets)
    53→
    54→    return list(droplets)
    55→
    56→
    57→@click.command(help="List machines")
    58→@click.option("--id", metavar="<MACHINE-ID>", help="Filter by id")
    59→@click.option("--name", "-n", metavar="<MACHINE-NAME>", help="Filter by name")
    60→@click.option("--tag", "-t", metavar="<TAG-TEXT>", help="Filter by tag")
    61→@click.option("--type", "-m", metavar="<MACHINE-TYPE>", help="Filter by type")
    62→@click.option("--region", "-r", metavar="<REGION>", help="Filter by region")
    63→@click.option("--output", "-o", metavar="<FORMAT>", help="Output format")
    64→@click.option(
    65→    "--all",
    66→    is_flag=True,
    67→    default=False,
    68→    help="All machines, including those not created by this tool or by other sessions",
    69→)
    70→@click.option("--quiet", "-q", is_flag=True, default=False, help="Only display machine IDs")
    71→@click.option(
    72→    "--unique",
    73→    is_flag=True,
    74→    default=False,
    75→    help="Return an error if there is more than one match",
    76→)
    77→@click.pass_context
    78→def command(context, id, name, tag, type, region, all, output, quiet, unique):
    79→    command_context: MainCmdCtx = context.obj
    80→
    81→    droplets = get_droplets(command_context, id, name, tag, type, region, all)
    82→    if unique and len(droplets) > 1:
    83→        fatal_error(f"ERROR: --unique match required but {len(droplets)} matches found.")
    84→
    85→    if output == "json":
    86→        print_json(droplets)
    87→    elif quiet:
    88→        print_quiet(droplets)
    89→    else:
    90→        print_normal(droplets)
    91→

     1→from dataclasses import dataclass
     2→
     3→TAG_MACHINE_CREATED = "machine:created"
     4→TAG_MACHINE_TYPE_PREFIX = "machine:type:"
     5→TAG_MACHINE_SESSION_PREFIX = "machine:session:"
     6→
     7→
     8→@dataclass
     9→class CliOptions:
    10→    debug: bool
    11→    quiet: bool
    12→    verbose: bool
    13→    dry_run: bool
    14→
    15→
    16→@dataclass
    17→class Config:
    18→    access_token: str
    19→    ssh_key: str
    20→    dns_zone: str
    21→    machine_size: str
    22→    image: str
    23→    region: str
    24→    project: str
    25→
    26→
    27→@dataclass
    28→class MainCmdCtx:
    29→    config: Config
    30→    session_id: str
    31→
    32→
    33→@dataclass
    34→class MachineConfig:
    35→    new_user_name: str
    36→    script_url: str
    37→    script_dir: str
    38→    script_path: str
    39→    script_args: str
    40→

File created successfully at: /home/david/projects/stirlingbridge/machine/tests/test_e2e.py

The file /home/david/projects/stirlingbridge/machine/pyproject.toml has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/Makefile has been updated successfully.

Using CPython 3.12.3 interpreter at: /usr/bin/python3
Creating virtual environment at: .venv
   Building machine @ file:///home/david/projects/stirlingbridge/machine
Downloading pygments (1.2MiB)
Downloading black (1.7MiB)
 Downloaded pygments
 Downloaded black
      Built machine @ file:///home/david/projects/stirlingbridge/machine
Installed 25 packages in 17ms

============================= test session starts ==============================
platform linux -- Python 3.12.3, pytest-9.0.2, pluggy-1.6.0 -- /home/david/projects/stirlingbridge/machine/.venv/bin/python
cachedir: .pytest_cache
rootdir: /home/david/projects/stirlingbridge/machine
configfile: pyproject.toml
collecting ... collected 33 items / 4 deselected / 29 selected

<Dir machine>
  <Package tests>
    <Module test_cli_integration.py>
      Integration tests that run the machine CLI as a subprocess, the same way a user would.
      <Class TestVersionCommand>
        Smoke test: the CLI runs and the version command works without any config.
        <Function test_version_runs>
        <Function test_help_runs>
      <Class TestEnvVarExpansionIntegration>
        End-to-end tests that verify environment variable expansion works
        when the actual machine tool is invoked with a config file.
        <Function test_env_var_expanded_in_config>
        <Function test_multiple_env_vars_expanded>
        <Function test_env_var_with_default_uses_default_when_unset>
        <Function test_env_var_with_default_uses_value_when_set>
        <Function test_missing_env_var_without_default_exits_with_error>
        <Function test_env_var_in_machine_config_section>
    <Module test_config.py>
      <Class TestExpandEnvVars>
        <Function test_plain_string_unchanged>
        <Function test_non_string_types_unchanged>
        <Function test_simple_variable_substitution>
        <Function test_variable_embedded_in_string>
        <Function test_multiple_variables_in_string>
        <Function test_default_value_when_var_unset>
        <Function test_default_value_ignored_when_var_set>
        <Function test_default_value_empty_string>
        <Function test_unset_variable_without_default_exits>
        <Function test_dict_values_expanded>
        <Function test_nested_dict_expanded>
        <Function test_list_values_expanded>
        <Function test_mixed_nested_structure>
    <Module test_input_validation.py>

tests/test_config.py::TestExpandEnvVars::test_variable_embedded_in_string PASSED [ 41%]
tests/test_config.py::TestExpandEnvVars::test_multiple_variables_in_string PASSED [ 44%]
tests/test_config.py::TestExpandEnvVars::test_default_value_when_var_unset PASSED [ 48%]
tests/test_config.py::TestExpandEnvVars::test_default_value_ignored_when_var_set PASSED [ 51%]
tests/test_config.py::TestExpandEnvVars::test_default_value_empty_string PASSED [ 55%]
tests/test_config.py::TestExpandEnvVars::test_unset_variable_without_default_exits PASSED [ 58%]
tests/test_config.py::TestExpandEnvVars::test_dict_values_expanded PASSED [ 62%]
tests/test_config.py::TestExpandEnvVars::test_nested_dict_expanded PASSED [ 65%]
tests/test_config.py::TestExpandEnvVars::test_list_values_expanded PASSED [ 68%]
tests/test_config.py::TestExpandEnvVars::test_mixed_nested_structure PASSED [ 72%]
tests/test_input_validation.py::TestInvalidMachineType::test_invalid_machine_type_error_message PASSED [ 75%]
tests/test_input_validation.py::TestInvalidMachineType::test_valid_machine_type_accepted PASSED [ 79%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_digital_ocean_section PASSED [ 82%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_access_token PASSED [ 86%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_ssh_key PASSED [ 89%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_machines_section PASSED [ 93%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_new_user_name_in_machine PASSED [ 96%]
tests/test_input_validation.py::TestCreateNoInitialize::test_no_initialize_without_type_no_crash PASSED [100%]

======================= 29 passed, 4 deselected in 3.86s =======================

File created successfully at: /home/david/projects/stirlingbridge/machine/tests/E2E.md

     1→name: Test
     2→
     3→on:
     4→  push:
     5→    branches:
     6→      - main
     7→  pull_request:
     8→    branches:
     9→      - main
    10→
    11→jobs:
    12→  test:
    13→    name: "Run Tests"
    14→    runs-on: ubuntu-latest
    15→    steps:
    16→      - name: "Clone project repository"
    17→        uses: actions/checkout@v4
    18→      - name: "Install uv"
    19→        uses: astral-sh/setup-uv@v4
    20→      - name: "Install Python"
    21→        run: uv python install 3.13
    22→      - name: "Install dependencies"
    23→        run: uv sync
    24→      - name: "Run tests"
    25→        run: uv run pytest tests/ -v
    26→

     1→name: Build and Release
     2→
     3→on:
     4→  push:
     5→    branches:
     6→      - main
     7→      - build-test
     8→
     9→jobs:
    10→  publish:
    11→    name: "Build and Release"
    12→    runs-on: ubuntu-latest
    13→    steps:
    14→      - name: "Clone project repository"
    15→        uses: actions/checkout@v4
    16→      - name: "Install uv"
    17→        uses: astral-sh/setup-uv@v4
    18→      - name: "Install Python"
    19→        run: uv python install 3.13
    20→      - name: "Get release tag"
    21→        id: release-tag
    22→        run: |
    23→          release_tag=$(./sh/make-release-tag.sh)
    24→          echo "release-tag=v${release_tag}" >> $GITHUB_OUTPUT
    25→      - name: "Build shiv package"
    26→        run: |
    27→          ./sh/build-package.sh
    28→      - name: "Upload package as a github release"
    29→        uses: softprops/action-gh-release@v2
    30→        with:
    31→          tag_name: ${{ steps.release-tag.outputs.release-tag }}
    32→          draft: ${{ endsWith('build-test', github.ref ) }}
    33→          files: ./build/machine
    34→

File created successfully at: /home/david/projects/stirlingbridge/machine/.github/workflows/e2e-test.yml

File created successfully at: /home/david/projects/stirlingbridge/machine/.claude/projects/-home-david-projects-stirlingbridge-machine/memory/project_e2e_tests.md

No files found

File created successfully at: /home/david/projects/stirlingbridge/machine/.claude/projects/-home-david-projects-stirlingbridge-machine/memory/MEMORY.md