Use the HCP Terraform API to programmatically trigger a speculative plan, poll for its completion, and parse the structured plan output to enforce a cost policy gate in CI

Steps

1. Compress the Terraform configuration directory into a tar.gz file and upload it to HCP Terraform as a configuration version using the POST /configuration-versions API endpoint with the auto-queue-runs: false flag
2. Trigger a speculative plan run by creating a run via POST /runs with plan-only: true referencing the workspace ID and configuration version ID; capture the returned run ID
3. Poll GET /runs/:id at intervals inspecting the status field until it reaches planned, errored, or discarded; implement exponential backoff and a maximum poll timeout to avoid infinite loops
4. Retrieve the structured plan JSON by following the run's relationships.plan.links.json-output URL; parse the resource_changes array to extract planned cost-relevant attributes such as instance types or storage sizes
5. Apply a cost policy rule in the CI script: if the planned changes include instance types not on an approved list or exceed a resource count threshold, post a policy violation comment to the pull request and exit non-zero to block merge
6. On policy pass, optionally trigger the actual apply run using the same run ID if the workspace is configured for API-driven runs, or leave the speculative plan result as an advisory artifact in the PR