fogies 0.0.0.dev2__tar.gz → 0.0.0.dev3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fogies
-Version: 0.0.0.dev2
+Version: 0.0.0.dev3
 Summary: 
 Author: James Fogarty
 Author-email: jayfo@users.noreply.github.com

{fogies-0.0.0.dev2 → 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.2"
+version = "0.0.0-dev.3"
 description = ""
 authors = [
     {name = "James Fogarty",email = "jayfo@users.noreply.github.com"}
@@ -12,7 +12,7 @@ requires-python = ">=3.14,<4.0"
 [tool.poetry]
 packages = [
     {include = "fogies", from = "src"},
-    {include = "paths.py", from = "."},
+    {include = "fogies_paths.py", from = "."},
 ]
 
 [tool.poetry.dependencies]
@@ -39,10 +39,9 @@ semver = "^3.0.4"
 [tool.basedpyright]
 typeCheckingMode = "recommended"
 pythonVersion = "3.14"
-include = ["paths.py", "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.dev2 → fogies-0.0.0.dev3}/src/fogies/tools/aws_environ.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import tomllib
 from pathlib import Path
 
@@ -57,7 +58,7 @@ def aws_environ(
     *,
     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;

{fogies-0.0.0.dev2 → fogies-0.0.0.dev3}/src/fogies/tools/command.py

@@ -1,3 +1,4 @@
+import contextlib
 import dataclasses
 import os
 import pathlib
@@ -64,13 +65,12 @@ def command_run(
     args_combined = [resolved_command] + (args or [])
     command_str = " ".join(args_combined)
 
-    if command_params.cwd is not None:
-        context_cd = context.cd(  # pyright: ignore[reportUnknownMemberType]
-            str(command_params.cwd)
-        )
-        with context_cd:
-            result = context.run(command_str, in_stream=command_params.in_stream)
-    else:
+    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.

{fogies-0.0.0.dev2 → fogies-0.0.0.dev3}/src/fogies/tools/environ.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import os
 from collections.abc import Mapping
 
@@ -87,7 +88,7 @@ def environ(
     *,
     raise_if_exists: bool = True,
     raise_if_changed: bool = True,
-) -> _EnvironContext:
+) -> contextlib.AbstractContextManager[None]:
     """Return a context manager that applies the given environment overrides.
 
     The *variables* mapping provides environment variable names and string values

{fogies-0.0.0.dev2 → fogies-0.0.0.dev3}/src/fogies/tools/ollama.py

@@ -1,5 +1,6 @@
 import io
 import pathlib
+import shutil
 import socket
 import subprocess
 import sys
@@ -38,7 +39,7 @@ class _PidWithCreateTime(BaseModel):
     """Persisted process identity state."""
 
     pid: int
-    create_time: float | None
+    create_time_seconds: int
 
 
 class _Ollama:
@@ -87,9 +88,7 @@ class _Ollama:
         if not pid_path.exists():
             return None
 
-        text = pid_path.read_text(encoding="utf-8").strip()
-        assert text is not None
-
+        text = pid_path.read_text(encoding="utf-8")
         state = _PidWithCreateTime.model_validate_json(text)
         assert state.pid > 0
 
@@ -149,12 +148,18 @@ class _Ollama:
         )
 
 
+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.
-        if pid.create_time is not None and process.create_time() != pid.create_time:
+        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)
@@ -189,10 +194,22 @@ def _terminate_pid(*, pid: _PidWithCreateTime) -> None:
 
 def _wait_until_listening(
     *,
-    timeout_s: float = _OLLAMA_LISTEN_PROBE_WAIT_TIMEOUT,
+    pid: _PidWithCreateTime,
+    timeout: float = _OLLAMA_LISTEN_PROBE_WAIT_TIMEOUT,
 ) -> None:
-    end = time.time() + timeout_s
+    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,
@@ -202,7 +219,7 @@ def _wait_until_listening(
         except OSError:
             pass
         time.sleep(_OLLAMA_LISTEN_POLL_INTERVAL)
-    raise TimeoutError("Ollama server did not become ready in time")
+    raise TimeoutError("Ollama server did not become ready")
 
 
 @contextmanager
@@ -236,19 +253,22 @@ def ollama(
 
     dir_name = "ollama_{}".format(version.replace(".", "_"))
     version_dir = binary_cache_path / dir_name
+    exe_path = version_dir / "ollama.exe"
 
-    if not version_dir.exists():
+    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()
 
-        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)
+            with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+                zf.extractall(version_dir)
+        except Exception:
+            shutil.rmtree(version_dir, ignore_errors=True)
+            raise
 
-    exe_path = version_dir / "ollama.exe"
     if not exe_path.exists():
         raise RuntimeError(
             "Ollama executable 'ollama.exe' not found in '{}'".format(version_dir)
@@ -272,17 +292,16 @@ def ollama_client(
     """
     with ollama(version=version, binary_cache_path=binary_cache_path) as ollama_binary:
         with ollama_binary.lock():
-            running = False
-
             # First check whether a process is already running.
-            pid = ollama_binary.pid
-            if pid is not None and pid.create_time is not None:
+            running = False
+            if ollama_binary.pid is not None:
                 try:
-                    proc = psutil.Process(pid.pid)
+                    proc = psutil.Process(ollama_binary.pid.pid)
                     running = (
                         proc.is_running()
                         and proc.status() != psutil.STATUS_ZOMBIE
-                        and proc.create_time() == pid.create_time
+                        and _create_time_seconds(proc.create_time())
+                        == ollama_binary.pid.create_time_seconds
                     )
                 except psutil.Error:
                     running = False
@@ -304,17 +323,22 @@ def ollama_client(
                 ollama_binary.set_pid(
                     _PidWithCreateTime(
                         pid=server_process.pid,
-                        create_time=psutil.Process(server_process.pid).create_time(),
+                        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)
 
-        try:
             # Wait until the server is listening.
-            _wait_until_listening()
+            _wait_until_listening(pid=ollama_binary.pid)
 
+        try:
             # Create the client.
             client = _ollama_client.Client()
             yield client
@@ -322,8 +346,6 @@ def ollama_client(
             with ollama_binary.lock():
                 ollama_binary.set_refcount(ollama_binary.refcount - 1)
 
-                if ollama_binary.refcount <= 0:
-                    pid = ollama_binary.pid
-                    if pid is not None:
-                        _terminate_pid(pid=pid)
+                if ollama_binary.refcount == 0:
+                    _terminate_pid(pid=ollama_binary.pid)
                     ollama_binary.reset_state()

{fogies-0.0.0.dev2 → fogies-0.0.0.dev3}/src/fogies/tools/terraform.py

@@ -1,435 +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") 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") 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)
-
-        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"))
-
-    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,
-        )
+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,
+        )