Module tool_check 

Tool preflight (C3).

Cross-cutting preflight checks for external tools an env-pack handler needs to do real work (e.g. terraform/kubectl/helm/docker/aws/gcloud/ az). The Phase A surface ships:

• ToolCheck / ToolCheckOutcome — the result shape every check returns, with structured Missing / VersionMismatch / AuthFailed / Unreachable / ProbeError variants and an honest install_hint.
• Generic primitives: check_binary_present and check_version_probe — handlers compose these into per-tool checks.
• A named-tool catalog (terraform, tofu, kubectl, helm, docker, podman, aws, gcloud, az) with minimum-version defaults the catalog tracks and honest install-hint text.
• Auth/scope probes (aws_caller_identity, gcloud_auth_list, az_account_show, kubectl_can_i) that go beyond binary presence to verify credentials and required permissions.

Phase A handlers (local-process, dev-store, stdout, in-memory) are all in-process and return an empty preflight via the default crate::env_packs::EnvPackHandler::preflight. Phase D handlers (K8s, cloud) compose this catalog by name.

gtc op env tool-check <env_id> aggregates per-binding ToolChecks into a structured JSON outcome.

No timeout discipline is enforced here — built-in Phase A handlers don’t shell out, so a hanging probe can’t surface yet. Phase D plumbing should wrap the slow primitives in wait_timeout-style guards before live use.

Structs

ToolCheck

A single preflight check.

Enums

ToolCheckOutcome

Outcome of a single ToolCheck.

Constants

MIN_AWS_VERSION

Minimum supported AWS CLI v2 version.

MIN_AZ_VERSION

Minimum supported Azure CLI version.

MIN_DOCKER_VERSION

Minimum supported Docker version.

MIN_GCLOUD_VERSION

Minimum supported gcloud version.

MIN_HELM_VERSION

Minimum supported Helm version.

MIN_KUBECTL_VERSION

Minimum supported kubectl version.

MIN_PODMAN_VERSION

Minimum supported Podman version (Docker-equivalent OCI runtime).

MIN_TERRAFORM_VERSION

Minimum supported Terraform version. We prefer OpenTofu (see plan §7 C3); Terraform is still accepted for environments stuck on it.

MIN_TOFU_VERSION

Minimum supported OpenTofu version. Bumped as the deployer adopts newer HCL features.

Functions

aws

Check aws is installed and at or above MIN_AWS_VERSION.

aws_caller_identity

aws sts get-caller-identity — verifies AWS credentials are configured and usable. region is optional; when present it is passed as --region.

az

Check az is installed and at or above MIN_AZ_VERSION.

az_account_show

az account show — verifies an Azure subscription is selected and the session is not expired.

check_binary_present

Verify a binary is on $PATH by invoking it with the given args (typically --version).

check_version_probe

Verify a binary’s --version-style output parses to a Version that satisfies required. The parser extracts a Version from the raw stdout — different tools embed their version in different shapes, so the caller owns the regex / split_whitespace choice.

docker

Check docker is installed and at or above MIN_DOCKER_VERSION.

gcloud

Check gcloud is installed and at or above MIN_GCLOUD_VERSION.

gcloud_auth_list

gcloud auth list --filter=status:ACTIVE — verifies a gcloud authentication is active.

helm

Check helm is installed and at or above MIN_HELM_VERSION.

kubectl

Check kubectl is installed and at or above MIN_KUBECTL_VERSION.

kubectl_can_i

kubectl auth can-i <verb> <resource> [-n <namespace>] — verifies the configured kubeconfig has the requested permission on the cluster. This goes beyond binary-present: it surfaces both kubeconfig reachability and RBAC sufficiency in one probe.

parse_first_semver_token

Extract a MAJOR.MINOR.PATCH from the first token that parses as one. Strips a leading v and drops any suffix after -/+ so v1.5.7-rc1 parses as 1.5.7. / is a separator so aws-cli/2.15.0 Python/3.11.6 yields 2.15.0.

parse_kubectl_version

Parses the first MAJOR.MINOR.PATCH from a kubectl version --client --output=yaml-style or plain --version string. Falls back to parse_first_semver_token.

podman

Check podman is installed and at or above MIN_PODMAN_VERSION.

terraform

Check terraform is installed and at or above MIN_TERRAFORM_VERSION. Prefer tofu for new environments — Terraform shells are accepted for legacy compatibility only.

tofu

Check tofu is installed and at or above MIN_TOFU_VERSION.