fogies 0.0.0.dev1__tar.gz → 0.0.0.dev3__tar.gz

{fogies-0.0.0.dev1 → fogies-0.0.0.dev3}/PKG-INFO

@@ -1,12 +1,16 @@
 Metadata-Version: 2.4
 Name: fogies
-Version: 0.0.0.dev1
+Version: 0.0.0.dev3
 Summary: 
 Author: James Fogarty
 Author-email: jayfo@users.noreply.github.com
 Requires-Python: >=3.14,<4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: filelock (>=3.25.2,<4.0.0)
+Requires-Dist: ollama (>=0.6.1,<0.7.0)
+Requires-Dist: psutil (>=7.2.2,<8.0.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
 Description-Content-Type: text/markdown
 
 # pyfogies

fogies-0.0.0.dev3/fogies_paths.py

@@ -0,0 +1,21 @@
+"""Paths used by tasks and tests in this development environment."""
+
+from pathlib import Path
+
+# Secrets directory.
+PATH_SECRETS = Path("secrets")
+
+# Path to the AWS profile secrets configuration file.
+PATH_SECRETS_AWS = PATH_SECRETS / "aws.toml"
+
+# AWS profile name for pyfogies test environment.
+AWS_PROFILE_PYFOGIES_TEST = "pyfogies-test"
+
+# Path to the Poetry secrets configuration file.
+PATH_SECRETS_POETRY = PATH_SECRETS / "poetry.toml"
+
+# Staging directory.
+PATH_STAGING = Path(".staging")
+
+# Binary cache directory (inside staging).
+PATH_STAGING_BINARY_CACHE = PATH_STAGING / "bin"

{fogies-0.0.0.dev1 → fogies-0.0.0.dev3}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "fogies"
 # Version follows semantic versioning <https://semver.org/>.
-version = "0.0.0-dev.1"
+version = "0.0.0-dev.3"
 description = ""
 authors = [
     {name = "James Fogarty",email = "jayfo@users.noreply.github.com"}
@@ -10,9 +10,16 @@ readme = "README.md"
 requires-python = ">=3.14,<4.0"
 
 [tool.poetry]
-packages = [{include = "fogies", from = "src"}]
+packages = [
+    {include = "fogies", from = "src"},
+    {include = "fogies_paths.py", from = "."},
+]
 
 [tool.poetry.dependencies]
+pydantic = "^2.12.5"
+ollama = "^0.6.1"
+filelock = "^3.25.2"
+psutil = "^7.2.2"
 
 [tool.poetry.group.dev.dependencies]
 # ^ allows all minor and patch releases.
@@ -21,6 +28,8 @@ packages = [{include = "fogies", from = "src"}]
 #   Example: ~1.2.3 will match versions >=1.2.3 but <1.3.0.
 basedpyright = "^1.36.1"
 black = "~25.12.0" # Black does not semver.
+boto3 = "^1.42.68"
+boto3-stubs-full = "^1.42.68"
 invoke = "^2.2.1"
 isort = "^7.0.0"
 poetry = "^2.2.1"
@@ -30,10 +39,9 @@ semver = "^3.0.4"
 [tool.basedpyright]
 typeCheckingMode = "recommended"
 pythonVersion = "3.14"
-include = ["src", "tasks", "tests"]
+include = ["fogies_paths.py", "src", "tasks", "tests"]
 allowedUntypedLibraries = ["invoke"]
 
 [build-system]
 requires = ["poetry-core>=2.0.0,<3.0.0"]
 build-backend = "poetry.core.masonry.api"
-

{fogies-0.0.0.dev1 → fogies-0.0.0.dev3}/src/fogies/tasks/test.py

@@ -10,7 +10,7 @@ from invoke.context import Context
 from invoke.tasks import Task, task
 
 
-def get_task_test() -> Task[Callable[[Context], None]]:
+def get_task_test(path_tests: str | None = None) -> Task[Callable[[Context], None]]:
     @task(name="test")  # pyright: ignore[reportUntypedFunctionDecorator]
     def task_test(context: Context) -> None:
         """
@@ -21,6 +21,9 @@ def get_task_test() -> Task[Callable[[Context], None]]:
         env = os.environ.copy()
         env["COLUMNS"] = str(shutil.get_terminal_size().columns)
 
+        # Default to current directory.
+        param_path_tests = path_tests if path_tests is not None else "."
+
         _ = context.run(
             command=" ".join(
                 [
@@ -28,7 +31,7 @@ def get_task_test() -> Task[Callable[[Context], None]]:
                     # Explicitly enable color output.
                     # Without this, output through invoke will not be in color.
                     "--color=yes",
-                    ".",
+                    param_path_tests,
                 ]
             ),
             echo=True,

fogies-0.0.0.dev3/src/fogies/terraform/backend.py

@@ -0,0 +1,17 @@
+"""Pydantic models for Terraform backend module variables and output."""
+
+from pydantic import BaseModel
+
+
+class BackendVars(BaseModel):
+    name: str
+    region: str
+    states: list[str] = []
+    tags: dict[str, str] = {}
+    force_destroy: bool = False
+
+
+class BackendOutput(BaseModel):
+    bucket_name: str
+    region: str
+    state_keys: dict[str, str]

fogies-0.0.0.dev3/src/fogies/tools/aws_environ.py

@@ -0,0 +1,80 @@
+"""Helpers for configuring AWS-related environment variables."""
+
+from __future__ import annotations
+
+import contextlib
+import tomllib
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from fogies.tools.environ import environ
+
+
+class _AwsProfile(BaseModel):
+    aws_access_key_id: str
+    aws_secret_access_key: str
+
+
+def _load_aws_profile_from_toml(profiles_path: Path, profile: str) -> _AwsProfile:
+    """Return AWS profile loaded from a TOML profiles file.
+
+    The file is expected to contain a table for each profile, for example:
+
+    [test]
+    aws_access_key_id = "value-id"
+    aws_secret_access_key = "value-secret"
+    """
+    if profiles_path.suffix != ".toml":
+        raise ValueError(
+            "AWS profiles file must have .toml extension, got '{}'".format(
+                profiles_path
+            )
+        )
+    if not profiles_path.exists():
+        raise FileNotFoundError(
+            "AWS profiles file '{}' does not exist".format(profiles_path)
+        )
+
+    with profiles_path.open("rb") as profiles_file:
+        data: dict[str, object] = tomllib.load(profiles_file)
+
+    try:
+        profile_raw = data[profile]
+    except KeyError as exc:
+        raise KeyError(
+            "AWS profile '{}' not found in '{}'".format(
+                profile,
+                profiles_path,
+            )
+        ) from exc
+
+    return _AwsProfile.model_validate(profile_raw)
+
+
+def aws_environ(
+    profiles_path: Path,
+    profile: str,
+    *,
+    raise_if_exists: bool = True,
+    raise_if_changed: bool = True,
+) -> contextlib.AbstractContextManager[None]:
+    """Return a context manager that applies AWS variables from a TOML file.
+
+    The *profiles_path* parameter specifies the AWS TOML profiles file to read;
+    it must have a ``.toml`` extension. The *profile* parameter specifies the
+    AWS profile name, which is mapped to a ``[<name>]`` table in the profiles
+    file.
+    """
+    aws_profile = _load_aws_profile_from_toml(
+        profiles_path=profiles_path, profile=profile
+    )
+    variables: dict[str, str] = {
+        "AWS_ACCESS_KEY_ID": aws_profile.aws_access_key_id,
+        "AWS_SECRET_ACCESS_KEY": aws_profile.aws_secret_access_key,
+    }
+    return environ(
+        variables=variables,
+        raise_if_exists=raise_if_exists,
+        raise_if_changed=raise_if_changed,
+    )

fogies-0.0.0.dev3/src/fogies/tools/command.py

@@ -0,0 +1,78 @@
+import contextlib
+import dataclasses
+import os
+import pathlib
+from typing import cast
+
+from invoke.context import Context
+from invoke.runners import Result
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class CommandParams:
+    """Params for execution via invoke."""
+
+    context: Context | None = None
+    cwd: pathlib.Path | None = None
+    in_stream: bool = True
+
+    def require_cwd(self, path: pathlib.Path) -> "CommandParams":
+        """Ensure cwd is set to *path*; return updated params or raise if conflicting."""
+        if self.cwd is None:
+            return dataclasses.replace(self, cwd=path)
+        if self.cwd == path:
+            return self
+        raise ValueError(
+            "CommandParams requires cwd '{}' but already has '{}'".format(
+                path,
+                self.cwd,
+            )
+        )
+
+
+def _resolve_command(
+    command: pathlib.Path,
+    cwd: pathlib.Path | None,
+) -> str:
+    """Return the command string to pass to the shell.
+
+    When *cwd* is set and *command* resolves to an existing file (a specific
+    binary), returns a path relative to *cwd*. Otherwise returns the command as
+    given so a name like \"bash\" is left for PATH (e.g. shutil.which).
+    """
+    if cwd is not None:
+        resolved = command.resolve()
+        if resolved.exists():
+            return os.path.relpath(resolved, cwd.resolve())
+    return str(command)
+
+
+def command_run(
+    *,
+    command: pathlib.Path,
+    command_params: CommandParams | None = None,
+    args: list[str] | None = None,
+) -> Result:
+    """Run a command via invoke run().
+
+    If *context* is provided, use context.run(). Otherwise create a new
+    Context and run the command there.
+    """
+    command_params = command_params or CommandParams()
+    context = command_params.context or Context()
+
+    resolved_command = _resolve_command(command, command_params.cwd)
+    args_combined = [resolved_command] + (args or [])
+    command_str = " ".join(args_combined)
+
+    cd_context = (
+        context.cd(str(command_params.cwd))  # pyright: ignore[reportUnknownMemberType]
+        if command_params.cwd is not None
+        else contextlib.nullcontext()
+    )
+    with cd_context:
+        result = context.run(command_str, in_stream=command_params.in_stream)
+
+    # invoke's Context.run() returns None when run with disown=True.
+    # Ensure future revisions to this code never introduce the parameter.
+    return cast(Result, result)

fogies-0.0.0.dev3/src/fogies/tools/environ.py

@@ -0,0 +1,108 @@
+"""Context managers for temporary environment variable overrides."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from collections.abc import Mapping
+
+
+class _EnvironContext:
+    """Context manager for environment variable overrides."""
+
+    def __init__(
+        self,
+        variables: Mapping[str, str],
+        *,
+        raise_if_exists: bool,
+        raise_if_changed: bool,
+    ) -> None:
+        self._variables: dict[str, str] = {
+            name: str(value) for name, value in variables.items()
+        }
+        self._raise_if_exists: bool = raise_if_exists
+        self._raise_if_changed: bool = raise_if_changed
+        self._original_variables: dict[str, str | None] = {}
+        self._applied_variables: list[str] = []
+
+    def _restore_originals(self) -> None:
+        """Restore each applied variable to its original value or remove it."""
+        for name in reversed(self._applied_variables):
+            original = self._original_variables.get(name)
+            if original is None:
+                if name in os.environ:
+                    del os.environ[name]
+            else:
+                os.environ[name] = original
+
+    def __enter__(self) -> None:
+        try:
+            for name, value in self._variables.items():
+                existing = os.environ.get(name)
+                if existing is not None and self._raise_if_exists:
+                    raise ValueError(
+                        "Environment variable '{}' already exists".format(name)
+                    )
+
+                self._original_variables[name] = existing
+                os.environ[name] = value
+                self._applied_variables.append(name)
+        except Exception:
+            # Roll back any changes made before the failure.
+            self._restore_originals()
+            raise
+        return None
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        exc_tb: object | None,
+    ) -> bool:
+        error: RuntimeError | None = None
+
+        # Enforce raise_if_changed only when the body exited normally.
+        if exc_type is None and self._raise_if_changed:
+            for name in self._applied_variables:
+                expected = self._variables[name]
+                current = os.environ.get(name)
+                if current != expected:
+                    error = RuntimeError(
+                        "Environment variable '{}' was modified while context manager was active".format(
+                            name
+                        )
+                    )
+                    break
+
+        # Always restore original values.
+        self._restore_originals()
+
+        if error is not None:
+            raise error
+
+        return False
+
+
+def environ(
+    variables: Mapping[str, str],
+    *,
+    raise_if_exists: bool = True,
+    raise_if_changed: bool = True,
+) -> contextlib.AbstractContextManager[None]:
+    """Return a context manager that applies the given environment overrides.
+
+    The *variables* mapping provides environment variable names and string values
+    to assign for the duration of the context.
+
+    For each variable:
+    - If raise_if_exists is True (default) and the variable already exists,
+      raises ValueError and leaves the environment unchanged.
+    - On normal exit, if raise_if_changed is True (default) and the value in
+      the environment differs from the value set by this context manager,
+      raises RuntimeError.
+    """
+    return _EnvironContext(
+        variables=variables,
+        raise_if_exists=raise_if_exists,
+        raise_if_changed=raise_if_changed,
+    )

fogies-0.0.0.dev3/src/fogies/tools/ollama.py

@@ -0,0 +1,351 @@
+import io
+import pathlib
+import shutil
+import socket
+import subprocess
+import sys
+import time
+import urllib.request
+import zipfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from http.client import HTTPResponse
+from typing import cast
+
+import ollama as _ollama_client
+import psutil
+from filelock import BaseFileLock, FileLock
+from pydantic import BaseModel
+
+_KNOWN_VERSIONS = [
+    "0.17.7",
+]
+
+_DEFAULT_VERSION = _KNOWN_VERSIONS[-1]
+
+_OLLAMA_URL_TEMPLATE = (
+    "https://github.com/ollama/ollama/releases/download"
+    "/v{version}/ollama-windows-amd64.zip"
+)
+
+_OLLAMA_LISTEN_ADDRESS: tuple[str, int] = ("127.0.0.1", 11434)
+_OLLAMA_LISTEN_PROBE_TIMEOUT = 0.25
+_OLLAMA_LISTEN_POLL_INTERVAL = 0.1
+_OLLAMA_LISTEN_PROBE_WAIT_TIMEOUT = 10.0
+_OLLAMA_TERMINATE_WAIT_TIMEOUT = 10.0
+
+
+class _PidWithCreateTime(BaseModel):
+    """Persisted process identity state."""
+
+    pid: int
+    create_time_seconds: int
+
+
+class _Ollama:
+    """Represents an Ollama CLI binary."""
+
+    _version: str
+    _path: pathlib.Path
+    _file_lock: BaseFileLock
+
+    def __init__(self, *, version: str, path: pathlib.Path) -> None:
+        self._version = version
+        self._path = path
+        self._file_lock = FileLock(str(self._lock_path), is_singleton=True)
+
+    @property
+    def binary_version(self) -> str:
+        """The Ollama binary version string."""
+        return self._version
+
+    @property
+    def binary_path(self) -> pathlib.Path:
+        """The path to the Ollama executable."""
+        return self._path
+
+    @property
+    def _pid_path(self) -> pathlib.Path:
+        """Return the PID file path for this binary."""
+        return self._path.with_suffix(".pid")
+
+    @property
+    def _refcount_path(self) -> pathlib.Path:
+        """Return the refcount file path for this binary."""
+        return self._path.with_suffix(".refcount")
+
+    @property
+    def _lock_path(self) -> pathlib.Path:
+        """Return the lock file path for this binary."""
+        return self._path.with_suffix(".lock")
+
+    @property
+    def pid(self) -> _PidWithCreateTime | None:
+        """Return process identity state, or None if not managed."""
+        self._assert_lock()
+
+        pid_path = self._pid_path
+        if not pid_path.exists():
+            return None
+
+        text = pid_path.read_text(encoding="utf-8")
+        state = _PidWithCreateTime.model_validate_json(text)
+        assert state.pid > 0
+
+        return state
+
+    @property
+    def refcount(self) -> int:
+        """Return the server refcount, or 0 if not managed."""
+        self._assert_lock()
+
+        refcount_path = self._refcount_path
+        if not refcount_path.exists():
+            return 0
+
+        text = refcount_path.read_text(encoding="utf-8").strip()
+        if not text:
+            return 0
+
+        return int(text)
+
+    @contextmanager
+    def lock(self) -> Iterator[None]:
+        """Acquire and hold the file lock."""
+        with self._file_lock:
+            yield
+
+    def _assert_lock(self) -> None:
+        assert (
+            self._file_lock.is_locked
+        ), "Must be accessed within an Ollama lock context."
+
+    def reset_state(self) -> None:
+        """Clear the server state files."""
+        self._assert_lock()
+
+        self._pid_path.unlink(missing_ok=True)
+        self._refcount_path.unlink(missing_ok=True)
+
+    def set_pid(self, pid: _PidWithCreateTime) -> None:
+        """Set the managed server PID state."""
+        self._assert_lock()
+
+        pid_path = self._pid_path
+
+        text = "{}\n".format(pid.model_dump_json())
+        _ = pid_path.write_text(text, encoding="utf-8")
+
+    def set_refcount(self, count: int) -> None:
+        """Set the managed server refcount state."""
+        self._assert_lock()
+
+        refcount_path = self._refcount_path
+
+        _ = refcount_path.write_text(
+            "{}\n".format(count),
+            encoding="utf-8",
+        )
+
+
+def _create_time_seconds(create_time: float) -> int:
+    """Convert process create_time to truncated integer seconds."""
+    return int(create_time)
+
+
+def _terminate_pid(*, pid: _PidWithCreateTime) -> None:
+    try:
+        process = psutil.Process(pid.pid)
+
+        # If the process has been restarted, the pid was reused, do not terminate it.
+        process_create_time_seconds = _create_time_seconds(process.create_time())
+        if process_create_time_seconds != pid.create_time_seconds:
+            return
+
+        children = process.children(recursive=True)
+        processes = [*children, process]
+
+        for process_to_end in processes:
+            try:
+                process_to_end.terminate()
+            except psutil.Error:
+                pass
+
+        _, alive = psutil.wait_procs(
+            processes,
+            timeout=_OLLAMA_TERMINATE_WAIT_TIMEOUT,
+        )
+        if not alive:
+            return
+
+        for process_to_kill in alive:
+            try:
+                process_to_kill.kill()
+            except psutil.Error:
+                pass
+
+        _ = psutil.wait_procs(
+            alive,
+            timeout=_OLLAMA_TERMINATE_WAIT_TIMEOUT,
+        )
+    except psutil.Error:
+        pass
+
+
+def _wait_until_listening(
+    *,
+    pid: _PidWithCreateTime,
+    timeout: float = _OLLAMA_LISTEN_PROBE_WAIT_TIMEOUT,
+) -> None:
+    end = time.time() + timeout
+    while time.time() < end:
+        try:
+            proc = psutil.Process(pid.pid)
+            alive = (
+                proc.is_running()
+                and proc.status() != psutil.STATUS_ZOMBIE
+                and _create_time_seconds(proc.create_time()) == pid.create_time_seconds
+            )
+        except psutil.Error:
+            alive = False
+        if not alive:
+            raise RuntimeError("Ollama server process exited before becoming ready")
+        try:
+            with socket.create_connection(
+                _OLLAMA_LISTEN_ADDRESS,
+                timeout=_OLLAMA_LISTEN_PROBE_TIMEOUT,
+            ):
+                return
+        except OSError:
+            pass
+        time.sleep(_OLLAMA_LISTEN_POLL_INTERVAL)
+    raise TimeoutError("Ollama server did not become ready")
+
+
+@contextmanager
+def ollama(
+    *,
+    version: str | None = None,
+    binary_cache_path: pathlib.Path,
+) -> Iterator[_Ollama]:
+    """Download an Ollama Windows CLI release and yield an Ollama handle.
+
+    *version* is the Ollama release tag version (e.g., "0.17.7"). The archive is
+    downloaded from the GitHub releases page if it does not already exist in
+    *binary_cache_path*. The CLI zip archive `ollama-windows-amd64.zip` is
+    fetched and the full folder structure is extracted into a versioned
+    directory inside *binary_cache_path* and used from there.
+    """
+    if sys.platform != "win32":
+        raise RuntimeError("Only implemented on Windows")
+
+    if version is None:
+        version = _DEFAULT_VERSION
+
+    if version not in _KNOWN_VERSIONS:
+        known = ", ".join(_KNOWN_VERSIONS)
+        raise ValueError(
+            "Unknown Ollama version '{}'; known versions: {}".format(
+                version,
+                known,
+            )
+        )
+
+    dir_name = "ollama_{}".format(version.replace(".", "_"))
+    version_dir = binary_cache_path / dir_name
+    exe_path = version_dir / "ollama.exe"
+
+    if not exe_path.exists():
+        version_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            url = _OLLAMA_URL_TEMPLATE.format(version=version)
+            response = cast(HTTPResponse, urllib.request.urlopen(url))
+            with response:
+                zip_bytes: bytes = response.read()
+
+            with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+                zf.extractall(version_dir)
+        except Exception:
+            shutil.rmtree(version_dir, ignore_errors=True)
+            raise
+
+    if not exe_path.exists():
+        raise RuntimeError(
+            "Ollama executable 'ollama.exe' not found in '{}'".format(version_dir)
+        )
+
+    yield _Ollama(version=version, path=exe_path)
+
+
+@contextmanager
+def ollama_client(
+    *,
+    version: str | None = None,
+    binary_cache_path: pathlib.Path,
+    show_window: bool = False,
+) -> Iterator[_ollama_client.Client]:
+    """Provide an Ollama Python client with a running local server.
+
+    Starts Ollama server in background and yields a configured
+    :class:`ollama.Client` instance connected to default local host.
+    Set *show_window* to True to allow a visible console window.
+    """
+    with ollama(version=version, binary_cache_path=binary_cache_path) as ollama_binary:
+        with ollama_binary.lock():
+            # First check whether a process is already running.
+            running = False
+            if ollama_binary.pid is not None:
+                try:
+                    proc = psutil.Process(ollama_binary.pid.pid)
+                    running = (
+                        proc.is_running()
+                        and proc.status() != psutil.STATUS_ZOMBIE
+                        and _create_time_seconds(proc.create_time())
+                        == ollama_binary.pid.create_time_seconds
+                    )
+                except psutil.Error:
+                    running = False
+
+            # If needed, start the server.
+            if not running:
+                ollama_binary.reset_state()
+
+                stdout = None if show_window else subprocess.DEVNULL
+                stderr = None if show_window else subprocess.DEVNULL
+                creation_flags = subprocess.CREATE_NEW_CONSOLE if show_window else 0
+
+                server_process = subprocess.Popen(
+                    [str(ollama_binary.binary_path), "serve"],
+                    stdout=stdout,
+                    stderr=stderr,
+                    creationflags=creation_flags,
+                )
+                ollama_binary.set_pid(
+                    _PidWithCreateTime(
+                        pid=server_process.pid,
+                        create_time_seconds=_create_time_seconds(
+                            psutil.Process(server_process.pid).create_time()
+                        ),
+                    )
+                )
+
+            # We now believe it is running.
+            assert ollama_binary.pid is not None
+
+            # Increment the refcount.
+            ollama_binary.set_refcount(ollama_binary.refcount + 1)
+
+            # Wait until the server is listening.
+            _wait_until_listening(pid=ollama_binary.pid)
+
+        try:
+            # Create the client.
+            client = _ollama_client.Client()
+            yield client
+        finally:
+            with ollama_binary.lock():
+                ollama_binary.set_refcount(ollama_binary.refcount - 1)
+
+                if ollama_binary.refcount == 0:
+                    _terminate_pid(pid=ollama_binary.pid)
+                    ollama_binary.reset_state()

fogies-0.0.0.dev3/src/fogies/tools/terraform.py

@@ -0,0 +1,445 @@
+import dataclasses
+import io
+import json
+import pathlib
+import sys
+import urllib.request
+import zipfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from http.client import HTTPResponse
+from typing import TypeVar, cast
+
+from invoke.runners import Result
+from pydantic import BaseModel, RootModel
+
+from fogies.terraform.backend import BackendOutput
+from fogies.tools.command import CommandParams, command_run
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class InitParams:
+    """Params for terraform init."""
+
+    migrate_state: bool = False
+    reconfigure: bool = False
+    upgrade: bool = False
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ApplyParams:
+    """Params for terraform apply."""
+
+    auto_approve: bool = False
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class DestroyParams:
+    """Params for terraform destroy."""
+
+    auto_approve: bool = False
+
+
+_KNOWN_VERSIONS = [
+    "1.14.4",
+]
+
+_DEFAULT_VERSION = _KNOWN_VERSIONS[-1]
+
+_TERRAFORM_URL_TEMPLATE = (
+    "https://releases.hashicorp.com/terraform"
+    "/{version}/terraform_{version}_windows_amd64.zip"
+)
+
+TerraformOutputModel = TypeVar("TerraformOutputModel", bound=BaseModel)
+
+
+class _TerraformCommandOutputEntryModel(BaseModel):
+    """One output entry from `terraform output -json`, wrapping a value."""
+
+    value: object
+    type: object
+    sensitive: bool
+
+
+class _TerraformCommandOutputModel(
+    RootModel[dict[str, _TerraformCommandOutputEntryModel]],
+):
+    """Root model for the full `terraform output -json` payload."""
+
+
+@contextmanager
+def terraform_tfbackend_s3(
+    *,
+    path: pathlib.Path,
+    backend: BackendOutput,
+    state: str,
+    delete_on_exit: bool = True,
+) -> Iterator[pathlib.Path]:
+    """Write S3 backend configuration to a file and yield the path.
+
+    The file is written as flat key/value entries, one per line, e.g.:
+
+    region = "us-west-2"
+    bucket = "pyfogies-test-backend-bucket"
+    key = "test-state-a/terraform.tfstate"
+    use_lockfile = true
+    """
+    if path.suffixes[-2:] != [".s3", ".tfbackend"]:
+        raise ValueError("Path '{}' must end with '.s3.tfbackend'".format(path))
+    if state not in backend.state_keys:
+        raise ValueError(
+            "State '{}' is not declared as part of backend. Declared states: {}.".format(
+                state,
+                ", ".join(sorted(backend.state_keys)),
+            )
+        )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        _ = f.write('region = "{}"\n'.format(backend.region))
+        _ = f.write('bucket = "{}"\n'.format(backend.bucket_name))
+        _ = f.write('key = "{}"\n'.format(backend.state_keys[state]))
+        _ = f.write("use_lockfile = true\n")
+    try:
+        yield path
+    finally:
+        if delete_on_exit and path.exists():
+            path.unlink()
+
+
+@contextmanager
+def terraform_tfvars(
+    *,
+    path: pathlib.Path,
+    variables: BaseModel,
+    delete_on_exit: bool = True,
+) -> Iterator[pathlib.Path]:
+    """Write in-memory variables to a file and yield the path for use with apply/destroy.
+
+    *path* is where the .tfvars.json file is written. *variables* must be a
+    Pydantic model; its fields are written as the Terraform variable set.
+    Yields *path* so the caller can pass it as the tfvars argument to apply()
+    or destroy(). If *delete_on_exit* is true, remove the file when exiting the
+    context.
+    """
+    suffixes = path.suffixes
+    if suffixes[-2:] != [".tfvars", ".json"]:
+        raise ValueError("Path '{}' must end with '.tfvars.json'".format(path))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(variables.model_dump(mode="json"), f, indent=2)
+    try:
+        yield path
+    finally:
+        if delete_on_exit and path.exists():
+            path.unlink()
+
+
+class _Terraform:
+    """Represents a Terraform binary."""
+
+    _version: str
+    _path: pathlib.Path
+
+    def __init__(self, *, version: str, path: pathlib.Path) -> None:
+        self._version = version
+        self._path = path
+
+    @property
+    def binary_version(self) -> str:
+        """The Terraform binary version string."""
+        return self._version
+
+    @property
+    def binary_path(self) -> pathlib.Path:
+        """The path to the Terraform executable."""
+        return self._path
+
+    def init(
+        self,
+        *,
+        command_params: CommandParams,
+        module_path: pathlib.Path,
+        tfbackend_path: pathlib.Path | None = None,
+        init_params: InitParams | None = None,
+    ) -> Result:
+        """Run terraform init.
+
+        *module_path* is the folder containing the Terraform files.
+        *init_params.migrate_state* when true passes -migrate-state to terraform init.
+        *init_params.reconfigure* when true passes -reconfigure to terraform init.
+        *init_params.upgrade* when true passes -upgrade to terraform init.
+        *tfbackend_path* when set passes -backend-config=<path> to terraform
+        init, where <path> is a backend configuration file.
+        """
+        command_params = command_params.require_cwd(module_path)
+        if init_params is None:
+            init_params = InitParams()
+        init_args = ["init"]
+        if tfbackend_path is not None:
+            init_args.extend(["-backend-config", str(tfbackend_path)])
+        if init_params.migrate_state:
+            init_args.append("-migrate-state")
+        if init_params.reconfigure:
+            init_args.append("-reconfigure")
+        if init_params.upgrade:
+            init_args.append("-upgrade")
+        return command_run(
+            command=self.binary_path,
+            command_params=command_params,
+            args=init_args,
+        )
+
+    def apply(
+        self,
+        *,
+        command_params: CommandParams,
+        module_path: pathlib.Path,
+        tfvars_path: pathlib.Path | list[pathlib.Path] | None = None,
+        apply_params: ApplyParams | None = None,
+    ) -> Result:
+        """Run terraform apply.
+
+        *module_path* is the folder containing the Terraform files (used as
+        working directory). If *apply_params.auto_approve* is true, pass
+        -auto-approve. *tfvars_path* is optional; when set, pass -var-file for
+        each path.
+        """
+        command_params = command_params.require_cwd(module_path)
+        if apply_params is None:
+            apply_params = ApplyParams()
+
+        apply_args = ["apply"]
+        if apply_params.auto_approve:
+            apply_args.append("-auto-approve")
+        if tfvars_path is not None:
+            paths = (
+                [tfvars_path] if isinstance(tfvars_path, pathlib.Path) else tfvars_path
+            )
+            for p in paths:
+                apply_args.extend(["-var-file", str(p)])
+
+        return command_run(
+            command=self.binary_path,
+            command_params=command_params,
+            args=apply_args,
+        )
+
+    def destroy(
+        self,
+        *,
+        command_params: CommandParams,
+        module_path: pathlib.Path,
+        tfvars_path: pathlib.Path | list[pathlib.Path] | None = None,
+        destroy_params: DestroyParams | None = None,
+    ) -> Result:
+        """Run terraform destroy.
+
+        *module_path* is the folder containing the Terraform files (used as
+        working directory). If *destroy_params.auto_approve* is true, pass
+        -auto-approve. *tfvars_path* is optional; when set, pass -var-file for
+        each path.
+        """
+        command_params = command_params.require_cwd(module_path)
+        if destroy_params is None:
+            destroy_params = DestroyParams()
+
+        destroy_args = ["destroy"]
+        if destroy_params.auto_approve:
+            destroy_args.append("-auto-approve")
+        if tfvars_path is not None:
+            paths = (
+                [tfvars_path] if isinstance(tfvars_path, pathlib.Path) else tfvars_path
+            )
+            for p in paths:
+                destroy_args.extend(["-var-file", str(p)])
+
+        return command_run(
+            command=self.binary_path,
+            command_params=command_params,
+            args=destroy_args,
+        )
+
+    def output(
+        self,
+        *,
+        command_params: CommandParams,
+        module_path: pathlib.Path,
+        output_model: type[TerraformOutputModel],
+    ) -> TerraformOutputModel:
+        """Run terraform output -json and parse the result into a Pydantic model.
+
+        *module_path* is the folder containing the Terraform files (used as
+        working directory). *output_model* is the Pydantic BaseModel subclass
+        used to validate the outputs. The JSON produced by
+        `terraform output -json` is simplified to a mapping from output names
+        to their `value` fields before validation.
+        """
+        command_params = command_params.require_cwd(module_path)
+        result = command_run(
+            command=self.binary_path,
+            command_params=command_params,
+            args=["output", "-json"],
+        )
+
+        parsed_terraform_output = _TerraformCommandOutputModel.model_validate_json(
+            result.stdout
+        )
+        recovered_values = {
+            name: entry.value for name, entry in parsed_terraform_output.root.items()
+        }
+        return output_model.model_validate(recovered_values)
+
+
+@contextmanager
+def terraform(
+    *,
+    version: str | None = None,
+    binary_cache_path: pathlib.Path,
+    command_params: CommandParams | None = None,
+    module_path: pathlib.Path | None = None,
+    tfbackend_path: pathlib.Path | None = None,
+    tfvars_path: pathlib.Path | list[pathlib.Path] | None = None,
+    init_on_entry: bool = False,
+    init_params: InitParams | None = None,
+    apply_on_entry: bool = False,
+    apply_params: ApplyParams | None = None,
+    delete_on_exit: bool = False,
+    destroy_params: DestroyParams | None = None,
+) -> Iterator[_Terraform]:
+    """Download a Terraform binary and yield a Terraform handle.
+
+    If *init_on_entry* is true, run init after preparing the binary; requires
+    *command_params* and *module_path*. If *apply_on_entry* is true, run
+    apply after init; requires *command_params* and *module_path*.
+    *tfbackend_path* is optional for init and, when set, is passed as
+    -backend-config=<path>. *tfvars_path* is optional for apply. If
+    *delete_on_exit* is true, run destroy when exiting the context; requires
+    *command_params* and *module_path*. *tfvars_path* is optional for destroy.
+    *version* when None uses the bundled default Terraform version.
+    """
+    if sys.platform != "win32":
+        raise RuntimeError("Only implemented on Windows")
+
+    if version is None:
+        version = _DEFAULT_VERSION
+
+    if version not in _KNOWN_VERSIONS:
+        known = ", ".join(_KNOWN_VERSIONS)
+        raise ValueError(
+            "Unknown Terraform version '{}'; known versions: {}".format(
+                version,
+                known,
+            )
+        )
+
+    if init_on_entry and (command_params is None or module_path is None):
+        raise ValueError("init_on_entry requires command_params and module_path")
+    if apply_on_entry and (command_params is None or module_path is None):
+        raise ValueError("apply_on_entry requires command_params and module_path")
+    if delete_on_exit and (command_params is None or module_path is None):
+        raise ValueError("delete_on_exit requires command_params and module_path")
+
+    exe_name = "terraform_{}.exe".format(version.replace(".", "_"))
+    exe_path = binary_cache_path / exe_name
+
+    if not exe_path.exists():
+        binary_cache_path.mkdir(parents=True, exist_ok=True)
+        try:
+            url = _TERRAFORM_URL_TEMPLATE.format(version=version)
+            response = cast(HTTPResponse, urllib.request.urlopen(url))
+            with response:
+                zip_bytes: bytes = response.read()
+
+            with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+                _ = exe_path.write_bytes(zf.read("terraform.exe"))
+        except Exception:
+            exe_path.unlink(missing_ok=True)
+            raise
+
+    if not exe_path.exists():
+        raise RuntimeError(
+            "Terraform executable 'terraform.exe' not found in '{}'".format(
+                binary_cache_path
+            )
+        )
+
+    tf = _Terraform(version=version, path=exe_path)
+
+    if init_on_entry:
+        assert command_params is not None
+        assert module_path is not None
+        _ = tf.init(
+            command_params=command_params,
+            module_path=module_path,
+            tfbackend_path=tfbackend_path,
+            init_params=init_params,
+        )
+
+    if apply_on_entry:
+        assert command_params is not None
+        assert module_path is not None
+        _ = tf.apply(
+            command_params=command_params,
+            module_path=module_path,
+            tfvars_path=tfvars_path,
+            apply_params=apply_params,
+        )
+
+    try:
+        yield tf
+    finally:
+        if delete_on_exit:
+            assert command_params is not None
+            assert module_path is not None
+            _ = tf.destroy(
+                command_params=command_params,
+                module_path=module_path,
+                tfvars_path=tfvars_path,
+                destroy_params=destroy_params,
+            )
+
+
+@contextmanager
+def terraform_output(
+    *,
+    version: str | None = None,
+    binary_cache_path: pathlib.Path,
+    command_params: CommandParams,
+    module_path: pathlib.Path,
+    tfbackend_path: pathlib.Path | None = None,
+    tfvars_path: pathlib.Path | list[pathlib.Path] | None = None,
+    init_on_entry: bool = False,
+    init_params: InitParams | None = None,
+    apply_on_entry: bool = False,
+    apply_params: ApplyParams | None = None,
+    delete_on_exit: bool = False,
+    destroy_params: DestroyParams | None = None,
+    output_model: type[TerraformOutputModel],
+) -> Iterator[TerraformOutputModel]:
+    """Run the terraform context manager, call output() internally, and yield the parsed result.
+
+    All entry/exit parameters are passed through to terraform(); the caller
+    sets *init_on_entry*, *apply_on_entry*, and *delete_on_exit* as needed.
+    Yields the output model; destroy runs on exit when *delete_on_exit* is true.
+    *version* when None uses the bundled default Terraform version.
+    """
+    with terraform(
+        version=version,
+        binary_cache_path=binary_cache_path,
+        command_params=command_params,
+        module_path=module_path,
+        tfbackend_path=tfbackend_path,
+        tfvars_path=tfvars_path,
+        init_on_entry=init_on_entry,
+        init_params=init_params,
+        apply_on_entry=apply_on_entry,
+        apply_params=apply_params,
+        delete_on_exit=delete_on_exit,
+        destroy_params=destroy_params,
+    ) as tf:
+        yield tf.output(
+            command_params=command_params,
+            module_path=module_path,
+            output_model=output_model,
+        )