Skip to content

CLAUDE.md

Latest commit

 

History

History
57 lines (44 loc) · 2.08 KB

CLAUDE.md

File metadata and controls

57 lines (44 loc) · 2.08 KB

CLAUDE.md

Project Overview

CLI tool (machine) for creating and managing VMs on DigitalOcean and Vultr. Built with Python and Click, packaged as a single-file executable via shiv.

  • Org: Stirlingbridge (github.com/stirlingbridge/machine)
  • License: AGPL-3.0-only
  • Python: >=3.8 (CI builds on 3.8)

Tech Stack

  • CLI framework: Click 8.1.7
  • Cloud providers: python-digitalocean 1.17.0, vultr-python >=0.1.5
  • Config: ruamel.yaml (reads ~/.machine/config.yml)
  • Build tooling: uv (dependency management), hatchling (build backend), shiv (zipapp packaging)

Project Structure

machine/             # Main package
  main.py            # Click group entry point
  config.py          # Config file loading
  provider.py        # Abstract CloudProvider base class
  di.py              # Dependency injection / globals
  factory.py         # VM creation factory
  cloud_config.py    # Cloud-init config generation
  providers/         # Provider implementations
    __init__.py      # Provider registry & factory
    digitalocean.py  # DigitalOcean provider
    vultr.py         # Vultr provider
  subcommands/       # Click subcommands (create, destroy, list, status, etc.)
sh/                  # Shell scripts (build, lint, dev-setup)
pyproject.toml       # Project metadata and dependencies

Development Commands

uv sync                    # Install dependencies (creates .venv)
uv run machine --help      # Run CLI in development
uv run ruff check machine/ # Lint
./sh/lint.sh --fix         # Auto-format with ruff, then lint
./sh/build-package.sh      # Build shiv executable to build/machine
make dev                   # Alias for uv sync
make build                 # Alias for build-package.sh
make lint                  # Alias for ruff check + format check

Code Style

  • Linter & Formatter: ruff (line length 132, max complexity 25, E203 ignored)
  • Config in pyproject.toml under [tool.ruff]

CI/CD

GitHub Actions workflow (.github/workflows/build-release.yml) builds a shiv package and publishes it as a GitHub release on push to main.