#104 · stacks/ts-cloud

glennmichael123 2 months ago

Context

Direct follow-on from #103 (April 2026 bill spike investigation). Even after that one is solved, we have no shared way to answer "what's costing us money this month?" without logging into the AWS console.

Proposal

Add a CLI command to ts-cloud that pulls Cost Explorer data and surfaces expensive culprits:

ts-cloud cost report                # current month, top-level service breakdown
ts-cloud cost report --month 2026-04
ts-cloud cost report --service s3 --by bucket
ts-cloud cost report --service s3 --by usage-type
ts-cloud cost report --top 10

Output sketch

AWS cost report — 2026-04 (\$687.42 total)

By service:
  S3 ......................... \$412.18  (60.0%)
  EC2 ........................ \$143.05  (20.8%)
  CloudFront ................. \$ 78.30  (11.4%)
  Data Transfer .............. \$ 32.40  ( 4.7%)
  Other ...................... \$ 21.49  ( 3.1%)

S3 top buckets:
  registry-stacksjs-prod ..... \$298.40  (DataTransfer-Out-Bytes: 2.4 TB)
  ...

Implementation notes

Use the AWS Cost Explorer API (ce:GetCostAndUsage)
Group by SERVICE, then drill-down by LINKED_ACCOUNT/USAGE_TYPE/RESOURCE_ID as needed
Cache responses locally for 1h — Cost Explorer charges $0.01/request, easy to rack up
Respect AWS_PROFILE correctly (see #99 — known foot-gun in this repo)

Acceptance

ts-cloud cost report works against real AWS creds
Top services + top S3 buckets + top usage types are inspectable
Cached so we don't burn money asking AWS what we spent money on
Documented in README

#103 — AWS bill spike investigation (this CLI is what would have caught it earlier)
#99 — S3Client AWS_PROFILE bug (don't repeat the mistake here)

glennmichael123 9 days ago

Status

Surface	Status
Top services for last full month	✅ Shipped — `cost:analyze` (commits ``32364cc`` → ``fd6a213``)
Profile / region wiring	✅ Shipped — strict `--profile`, see #99 / #105
1h response cache ($0.01/req billing)	✅ Shipped — see #106
Markdown report output	✅ Shipped — `--output ./aws.md` (``d8783dc``)
Top buckets (S3 by-bucket breakdown)	⏳ Filed separately (issue link below)
Top egress (data-transfer breakdown)	⏳ Filed separately (issue link below)
README / docs	✅ Shipped — `docs/features/cost.md`

The remaining drilldowns (top buckets, top egress) need either Cost & Usage Report ingestion or VPC Flow Logs analysis, neither of which is a small follow-up. Splitting into discrete issues so this tracker can close.

glennmichael123 9 days ago

Splitting the remaining drilldowns out so this tracker can close:

#113 — top S3 buckets by spend (per-bucket breakdown via CUR or cost-allocation tags)
#114 — top egress endpoints (UsageType breakdown via Cost Explorer + optional VPC Flow Logs correlation)

Everything else from the original scope shipped:

`cost:analyze` ranks services for the last full month
Strict `--profile` semantics (#99)
`s3:ListBuckets` parser bug fix (#105)
1h response cache (#106)
`--output ./aws.md` markdown report
`docs/features/cost.md`

Stub commands (`cost`, `cost:breakdown`, `resources`, `resources:unused`, `optimize`) are guarded with "not implemented" warnings + tracked in #108–#112.