Feature full Stack deployment lifecycle resources (groups → runs → steps → states → diagnostics)

[isivaselvan]

Description

Add full Stack deployment lifecycle resources (groups → runs → steps → states → diagnostics)

Why this change is needed

The pytfe SDK had no coverage for the operational side of HCP Terraform Stacks. The existing client.stacks and client.stack_configurations resources let you create and read a stack, but nothing let you inspect or drive a deployment once it started — no way to list deployment groups, track individual runs, advance a pending operator step, read the current state, or investigate a diagnostic. This PR fills that gap completely.

What was changed

8 new resource services wired into TFEClient:

Attribute	Resource	Key operations
client.stack_deployments	Stack deployments	list(stack_id)
client.stack_deployment_groups	Deployment groups	list, read, read_by_name, approve_all_plans, rerun
client.stack_deployment_runs	Deployment runs	list, read, approve_all_plans, cancel
client.stack_deployment_steps	Deployment steps	list, read, advance, list_diagnostics, download_artifact
client.stack_states	Stack states	list, read, download_description
client.stack_configuration_summaries	Config summaries	list
client.stack_deployment_group_summaries	Group summaries	list
client.stack_diagnostics	Stack diagnostics	read, acknowledge

New and updated models (models):

• stack_deployment.py — StackDeployment, StackDeploymentListOptions, StackDeploymentIncludeOpt
• stack_deployment_group.py — StackDeploymentGroup, DeploymentGroupStatus, StackDeploymentGroupListOptions, StackDeploymentGroupRerunOptions, StackDeploymentGroupStatusCounts, StackDeploymentGroupSummary, StackDeploymentGroupSummaryListOptions
• stack_deployment_run.py — StackDeploymentRun, DeploymentRunStatus, StackDeploymentRunListOptions, StackDeploymentRunReadOptions, StackDeploymentRunIncludeOpt (5 values, all snake_case per API spec)
• stack_deployment_step.py — StackDeploymentStep, DeploymentStepStatus, StackDeploymentStepArtifactType, StackDeploymentStepIncludeOpt, StackDeploymentStepListOptions, StackDeploymentStepReadOptions, StackDiagnostic, StackDiagnosticListOptions
• stack_configuration.py (extended) — StackConfigurationSummary, StackConfigurationSummaryListOptions, StackConfigurationSummaryGroupStatus, StackConfigurationSummaryRunStatus
• stack_state.py (new file) — StackState, StackStateComponent (correct wire fields: address, component-address, instance-correlator, component-correlator, resource-instance-count), StackStateListOptions

New errors in errors.py:

• InvalidStackDeploymentGroupIDError, InvalidStackDeploymentRunIDError, InvalidStackDeploymentStepIDError, InvalidStackStateIDError, InvalidStackDiagnosticIDError

Include param correctness fix: StackDeploymentRunIncludeOpt and StackDeploymentStepIncludeOpt use snake_case values (e.g. "stack_deployment_group", "stack_approval") matching the HCP Terraform API — not hyphenated strings.

Notable implementation decisions

• StackStateComponent is a separate model from StackComponent (used in stack-configurations). The state variant carries per-instance tracking fields (instance-correlator, resource-instance-count) rather than config fields (name, expanded, removed). Verified against the live API wire format.
• StackConfigurationSummary includes two nested rollup objects — group_status_summary and run_status_summary — that the API returns but go-tfe does not model. These give a quick view of how many deployment groups/runs succeeded, failed, or were abandoned for each configuration.
• stack_configuration_summaries and stack_deployment_group_summaries pagination is standard (not non-paginated), so _list() is used normally.

Testing

• 34 new unit test functions across 8 new test files (1139 total, up from 1104)
• Every public method has an invalid-ID test and a success path
• Relationship hydration verified (stubs populated from relationships block)
• All examples live-verified against a real HCP Terraform organization with a Kubernetes stack (st-GTFErQVpEN) running 3 deployments (dev/staging/prod)

Testing plan

External links

• Stack Deployment Group
• Stack Deployment Run
• Stack Deployment Steps

Output from tests

Including output from tests may require access to a TFE instance. Ignore this section if you have no environment to test against.

Rollback Plan

Changes to Security Controls

PCI review checklist

• I have documented a clear reason for, and description of, the change I am making.

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.

• If applicable, I've documented the impact of any changes to security controls.

  Examples of changes to security controls include using new access control methods, adding or removing logging pipelines, etc.

If you have any questions, please contact your direct supervisor, GRC (#team-grc), or the PCI working group (#proj-pci-reboot). You can also find more information at PCI Compliance.