@aaa-sentinel/iac-cost 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AAA Sentinel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,194 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @aaa-sentinel/iac-cost
+
+Comments the **monthly cost delta of a Terraform plan** on the pull request that introduces it,
+so the price of a change is visible while it is still cheap to change.
+
+> ### 💲 Infrastructure cost estimate
+>
+> **Coverage: 3 of 8 billable resources priced** (4 more have no cost by design).
+>
+> **Estimated change: +$74.46/mo** (list price, USD)
+>
+> | Resource | Change | Qty | Delta |
+> | --- | --- | --- | --- |
+> | `aws_instance` | new | 2 | +$121.18/mo |
+> | `azurerm_linux_virtual_machine` | removed | 1 | -$46.72/mo |
+>
+> <details><summary>Not priced (5 resources)</summary></details>
+
+## Requirements
+
+- Node.js 20 or newer.
+- An OAuth2 application with the `iac:estimate` scope, created in the
+  [developer portal](https://app.aaa-sentinel.com/developer/apps).
+  That scope grants **nothing else** — it cannot read your accounts, findings or reports —
+  which is what makes it safe to paste into a CI that third parties can trigger.
+- A **Pro** or **Business** plan.
+
+## Usage
+
+```bash
+terraform plan -out=plan.tfplan
+terraform show -json plan.tfplan > plan.json
+
+npx @aaa-sentinel/iac-cost plan.json          # or: … | npx @aaa-sentinel/iac-cost
+```
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `IAC_COST_CLIENT_ID` | yes | Client ID of the OAuth2 application |
+| `IAC_COST_CLIENT_SECRET` | yes | Client secret. Store it as an encrypted CI secret |
+| `IAC_COST_BASE_URL` | no | Defaults to `https://api.aaa-sentinel.com`. Must be `https` — the secret is never sent over plain HTTP |
+
+The Markdown comment goes to **stdout**; warnings go to **stderr**. If there is nothing to
+say, stdout is empty.
+
+### It never fails your build
+
+The exit code is **always 0**. A missing credential, a network error, an unreadable plan or an
+outage on our side prints a one-line warning and stops. A cost comment is not a quality gate, and
+our availability must not become a dependency of your deployments.
+
+## What actually leaves your machine
+
+Not the plan. `terraform show -json` output carries CIDRs, account identifiers and, often,
+secrets in clear text. Before anything is sent, the plan is reduced **on your machine** to a
+whitelist: resource type, action (`create`/`update`/`delete`/`replace`), how many instances the
+block produces, and the handful of attributes that move the price (instance size, region, OS).
+Everything else is dropped before serialising, and the projection is never written to the CI log.
+
+## Reading the number
+
+- **List price.** Neither AWS, Azure nor Google returns what *you* pay. Enterprise agreements
+  (EDP/EA/CUD) and existing reservations or Savings Plans are invisible at pull request time —
+  a reservation that already covers the new resource makes the real marginal cost zero.
+- **Priced in USD, shown in your organization's currency.** USD is what the providers publish, and
+  the API always returns it (`...Usd` fields). If your AAA Sentinel organization displays amounts
+  in EUR or GBP, the comment shows the converted amount instead, marked with `≈` and with the ECB
+  reference rate and its date spelled out — it is an estimate on top of an estimate, and the same
+  unchanged pull request can move a little as the exchange rate does. Organizations in USD, or a
+  day with no exchange rate available, get plain USD.
+- **Coverage leads, not the total.** When fewer than half of the billable resources can be
+  priced, the breakdown is published but the total is withheld. A total built from 2 resources
+  out of 30 is not a partial estimate, it is noise — and it would end up quoted in the review as
+  if it were the figure.
+- **An unknown region is treated as an unsupported one.** In AWS the region lives in the
+  `provider` block rather than the resource, so `terraform show -json` often leaves it unknown.
+  We say we do not know rather than substituting another region's price.
+
+Currently priced: **AWS** (EC2 on demand) and **Azure** (virtual machines). Anything else is
+reported as not priced, never as free.
+
+## GitHub Actions
+
+Posts one comment per pull request and **updates it in place** on later pushes instead of
+stacking a new one each time. The token is the one the run already injects — no personal access
+token, no app installation.
+
+```yaml
+name: Infrastructure cost
+on: pull_request
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  cost:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hashicorp/setup-terraform@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - run: terraform init
+      - run: terraform plan -out=plan.tfplan
+      - run: terraform show -json plan.tfplan > plan.json
+
+      - name: Estimate cost
+        env:
+          IAC_COST_CLIENT_ID: ${{ secrets.IAC_COST_CLIENT_ID }}
+          IAC_COST_CLIENT_SECRET: ${{ secrets.IAC_COST_CLIENT_SECRET }}
+        run: npx --yes @aaa-sentinel/iac-cost plan.json > comment.md
+
+      - name: Comment on the pull request
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.number }}
+        run: |
+          [ -s comment.md ] || exit 0
+          id=$(gh api --paginate "repos/$GITHUB_REPOSITORY/issues/$PR/comments" \
+                 --jq '.[] | select((.body // "") | contains("<!-- aaa-sentinel:iac-cost -->")) | .id' \
+               | head -n1)
+          if [ -n "$id" ]; then
+            gh api -X PATCH "repos/$GITHUB_REPOSITORY/issues/comments/$id" -F body=@comment.md
+          else
+            gh api -X POST "repos/$GITHUB_REPOSITORY/issues/$PR/comments" -F body=@comment.md
+          fi
+```
+
+> `continue-on-error` is not decoration: without it, a GitHub API hiccup while posting the comment
+> would fail the job, and a cost comment must never be able to do that.
+
+> On a pull request from a fork, GitHub gives the run a read-only token, so the comment step is
+> skipped. That is a GitHub restriction and it applies to every tool that comments on pull
+> requests, not just this one.
+
+## Bitbucket Pipelines
+
+Bitbucket does not inject a token that can write to the repository, so create a **Repository
+Access Token** with the `pullrequest:write` scope and store it as a secured repository variable
+named `BB_TOKEN`.
+
+```yaml
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          name: Infrastructure cost
+          image: hashicorp/terraform:latest
+          script:
+            - apk add --no-cache nodejs npm curl jq
+            - terraform init
+            - terraform plan -out=plan.tfplan
+            - terraform show -json plan.tfplan > plan.json
+            - npx --yes @aaa-sentinel/iac-cost plan.json > comment.md
+            - |
+              set +e
+              [ -s comment.md ] || exit 0
+              API="https://api.bitbucket.org/2.0/repositories/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG/pullrequests/$BITBUCKET_PR_ID/comments"
+              BODY=$(jq -Rs . < comment.md)
+              ID=$(curl -sf -H "Authorization: Bearer $BB_TOKEN" "$API?pagelen=100" \
+                    | jq -r '[.values[] | select((.content.raw // "") | contains("<!-- aaa-sentinel:iac-cost -->"))][0].id // empty')
+              if [ -n "$ID" ]; then
+                curl -sf -X PUT -H "Authorization: Bearer $BB_TOKEN" -H 'Content-Type: application/json' \
+                  -d "{\"content\":{\"raw\":$BODY}}" "$API/$ID"
+              else
+                curl -sf -X POST -H "Authorization: Bearer $BB_TOKEN" -H 'Content-Type: application/json' \
+                  -d "{\"content\":{\"raw\":$BODY}}" "$API"
+              fi
+              exit 0
+```
+
+> The `set +e` and the final `exit 0` are there for the same reason as `continue-on-error` on
+> GitHub: a failure while commenting must not fail the pipeline. A deleted comment has a null
+> `content.raw`, hence the `// ""` — without it `jq` aborts and the comment is posted again
+> instead of updated.
+
+## Why there is no comment
+
+| What you see | Why |
+| --- | --- |
+| No comment at all | The plan changes no billable resource, or the credentials are missing — check the step log, the reason is always printed |
+| A breakdown with no total | Fewer than half of the billable resources could be priced |
+| `region could not be resolved from the plan` | The region comes from a variable or an aliased provider, so the plan does not say which one applies |
+| `provider recognized, pricing not connected yet` | A cloud we support but whose catalogue is not connected yet (Google) |
+| `no matching price found in the catalog` | The size exists in the plan but not in that region's catalogue — an instance type not offered there, or a resource we price only for some families |
+
+## License
+
+MIT — see [LICENSE](LICENSE). The licence covers this client only; access to the API is governed by
+the terms of service at <https://app.aaa-sentinel.com>.