@jadenrazo/cloudcost-mcp 0.5.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-04-15
+
+First stable release. No breaking API changes from 0.5 — this version ratifies the existing surface as SemVer-locked. See [`MIGRATION.md`](./MIGRATION.md) for details.
+
+### Added
+- **`STABILITY.md`**: Formal stability contract defining the SemVer-locked public surface (11 MCP tools, CLI binaries, package entry points) and the change-classification policy.
+- **`MIGRATION.md`**: 0.x → 1.0 migration guide and forward-looking support policy.
+- **Smoke integration tests**: Live-API smoke coverage for AWS Bulk Pricing, Azure Retail Prices, and GCP Cloud Billing Catalog, gated behind `RUN_INTEGRATION=1`. New `integration-smoke` CI job runs on manual dispatch and weekly schedule (Mondays 12:00 UTC).
+- **Publish workflow gates**: `npm audit --audit-level=high` and `npm test` now run before `npm publish`, preventing broken or vulnerable releases.
+
+### Security
+- Resolved transitive advisories via npm `overrides`:
+  - `hono` → `^4.12.12` (GHSA-26pp-8wgv-hjvm, GHSA-r5rp-j6wh-rvv4, GHSA-xf4j-xp2r-rqqx, GHSA-wmmm-f939-6g9c, GHSA-xpcf-pg52-r92g)
+  - `@hono/node-server` → `^1.19.13` (GHSA-92pp-h63x-v22m)
+  - `path-to-regexp` → `^8.4.0` (GHSA-j3q9-mxjg-w52f, GHSA-27v5-c462-wpq7)
+  - `vite` → `^7.3.2` (GHSA-4w7w-66w2-5vf9, GHSA-v2wj-q39q-566r)
+- `npm audit --audit-level=high` now reports zero vulnerabilities.
+
+### Packaging
+- `STABILITY.md`, `MIGRATION.md`, and `CHANGELOG.md` are now included in the published npm tarball.
+
+## [0.4.0] - 2026-03-28
+
+### Added
+- **Multi-IaC support**: CloudFormation (JSON/YAML), Pulumi (stack export), and Bicep/ARM template parsing via unified `IaCParser` interface with auto-format detection
+- **`analyze_plan` tool**: Parse `terraform plan -json` output for precise before/after cost-of-change analysis
+- **`compare_actual` tool**: Parse `.tfstate` files to compare actual infrastructure costs against estimates
+- **`price_trends` tool**: Historical pricing with SQLite-backed price snapshots, change tracking, and trend queries
+- **`detect_anomalies` tool**: Cost anomaly detection with budget checks, price change alerts, concentration risk, and right-sizing hints
+- **API Gateway pricing**: AWS REST/HTTP/WebSocket, Azure API Management, GCP API Gateway
+- **WAF pricing**: AWS WAFv2, Azure WAF Policy
+- **OpenSearch pricing**: AWS OpenSearch Domain with per-instance-type tables
+- **Messaging pricing**: AWS SNS/MQ Broker, Azure Service Bus/Event Hubs, GCP Pub/Sub
+- **ML/AI pricing**: AWS SageMaker endpoints (40+ instance types), GCP Vertex AI (confidence: low)
+- **Expanded Redis**: Full Azure Redis Cache and GCP Redis Instance support
+- **ESLint + Prettier**: Flat config ESLint with TypeScript rules, Prettier formatting enforced
+- **Coverage thresholds**: 70%+ statement/branch/function/line coverage enforced via vitest
+- **Performance benchmarks**: Parsing, pricing cache, and calculator benchmarks via `vitest bench`
+- **CI hardening**: Security audit job, Prettier format check, concurrency groups, job timeouts
+- **SECURITY.md**: Vulnerability reporting policy and security design documentation
+- **ARCHITECTURE.md**: Layered architecture documentation with extension guides
+
+### Changed
+- Refactored `bulk-loader.ts` (929 -> 708 lines) into focused modules: csv-parser, fallback-data
+- Refactored `resource-extractor.ts` (778 -> 299 lines) into per-provider extractors
+- Refactored `retail-client.ts` (614 -> 499 lines) with extracted fallback-data
+- Replaced ~40 `any` types in pricing modules with proper TypeScript interfaces
+- Updated CI pipeline with security audit job and format checking
+
+### Fixed
+- picomatch HIGH severity vulnerability (ReDoS + method injection)
+- Unused imports and variables across codebase (ESLint cleanup)
+
+### Security
+- Resolved picomatch 4.0.0-4.0.3 vulnerability via npm audit fix
+- Added `npm audit --audit-level=high` to CI pipeline
+
+## [0.3.0] - 2026-03-14
+
+### Added
+
+- `what_if` MCP tool for hypothetical pricing scenarios (change instance types, regions, commitment levels; see cost delta without modifying Terraform)
+- Multi-currency support on `estimate_cost`, `compare_providers`, `what_if`: USD, EUR, GBP, JPY, CAD, AUD, INR, BRL
+- Spot/preemptible instance pricing model via `CLOUDCOST_PRICING_MODEL` or per-scenario in `what_if`
+- Cost projections over 3/6/12/36-month horizons with reserved instance comparisons (`src/calculator/projection.ts`)
+- Tag-based cost attribution and `group_by` report option for grouping by team, environment, or any resource tag
+- Budget alerts via `CLOUDCOST_BUDGET_MONTHLY`, `CLOUDCOST_BUDGET_PER_RESOURCE`, `CLOUDCOST_BUDGET_WARN_PCT`
+- Terraform module expansion: referenced modules (`source = "..."`) resolved during parsing; controlled by `CLOUDCOST_RESOLVE_MODULES`
+- Resource dependency graph via `include_dependencies` option on `analyze_terraform`
+- OpenTofu `.tofu` file support alongside `.tf` files
+- Data transfer cost integration (inter-region and internet egress) via `CLOUDCOST_INCLUDE_DATA_TRANSFER`
+- FOCUS-compliant export format. Pass `format: "focus"` to `compare_providers`
+- Live GCP Cloud Billing Catalog API client with automatic fallback to bundled data
+- Container Registries, Secrets Management, and DNS resource types across all three providers
+- GitHub Actions composite action for posting cost estimates as PR comments
+- `currency` input on the GitHub Actions composite action
+
+### Changed
+
+- GCP pricing now attempts the live Cloud Billing Catalog API first and falls back to bundled data; `pricing_source` reflects `"live"` or `"bundled"` accordingly
+- `compare_providers` `format` parameter now accepts `focus` in addition to `markdown`, `json`, and `csv`
+- `analyze_terraform` `include_dependencies` option now returns a full dependency adjacency list alongside the resource inventory
+
+### Fixed
+
+- Variable references that were not resolved when a `terraform.tfvars` file contained complex expressions are now handled with a safe fallback rather than surfacing a parse error
+- Concurrent pricing fetches for the same AWS region no longer trigger duplicate CSV downloads; a single in-flight request is now shared across callers
+
+## [0.1.0] - 2026-03-09
+
+### Added
+
+- Six MCP tools exposed over stdio: `analyze_terraform`, `estimate_cost`, `compare_providers`, `get_equivalents`, `get_pricing`, and `optimize_cost`
+- Multi-cloud cost analysis across AWS, Azure, and GCP from a single Terraform codebase
+- HCL/Terraform parsing via `@cdktf/hcl2json` with full variable resolution, including `terraform.tfvars` support
+- Real-time pricing from public APIs with no API keys or cloud credentials required (AWS Bulk Pricing CSV/JSON, Azure Retail Prices REST API)
+- Streaming ingestion of the AWS EC2 bulk pricing CSV (~267 MB) line-by-line to avoid loading the full file into memory; all on-demand prices for a region are extracted in one pass
+- Bundled GCP pricing data covering Compute Engine, Cloud SQL, Cloud Storage, Persistent Disk, and infrastructure services across all major regions
+- Graceful fallback to built-in pricing tables with size-interpolation when live sources are unavailable; every price includes a `pricing_source` field (`live`, `fallback`, or `bundled`) for transparency
+- SQLite-backed pricing cache (`better-sqlite3`) at `~/.cloudcost/cache.db` with a configurable TTL (default 24 hours), shared across all tools per server lifetime
+- Cross-provider resource and instance type mapping covering 70+ AWS instance types (including Graviton/ARM families), 40+ Azure VM sizes, and 20+ GCP machine types with full bidirectional lookup
+- Support for five resource categories: compute, database, storage, networking, and Kubernetes, across all three providers
+- Reserved instance and savings plan pricing analysis within the `optimize_cost` tool alongside right-sizing and cross-provider switching recommendations
+- Cost reports in Markdown, JSON, and CSV formats with per-resource monthly and yearly breakdowns and confidence scores
+- Three-layer configuration system: built-in defaults → `~/.cloudcost/config.json` → `CLOUDCOST_*` environment variables
+- ESM-only package targeting Node.js 20+, built with `tsup` and tested with `vitest`

package/MIGRATION.md

@@ -0,0 +1,40 @@
+# Migration Guide
+
+## 0.x → 1.0
+
+**There are no breaking API changes.** v1.0 ratifies the existing v0.5 surface as stable under [Semantic Versioning](https://semver.org/). If your integration works on v0.5.x it will work on v1.0.0 without modification.
+
+### What's new in 1.0
+
+- Formal stability contract — see [`STABILITY.md`](./STABILITY.md).
+- Security advisories in transitive dependencies (hono, `@hono/node-server`, path-to-regexp, vite) resolved via npm overrides.
+- Smoke integration tests against live provider pricing APIs, runnable via `RUN_INTEGRATION=1` and scheduled weekly in CI.
+- Hardened npm publish workflow (tests + audit gate releases).
+
+### Locked-in public surface
+
+The following are now SemVer-locked. Any breaking change to them requires a 2.0.
+
+- MCP tools: `analyze_terraform`, `estimate_cost`, `compare_providers`, `get_equivalents`, `get_pricing`, `optimize_cost`, `what_if`, `analyze_plan`, `compare_actual`, `price_trends`, `detect_anomalies`
+- CLI binaries: `cloudcost-mcp`, `cloudcost`
+- Node engines: `>=20.0.0`
+
+### Node.js
+
+Node 20 remains the minimum. No change from v0.5.
+
+### Support policy going forward
+
+- Latest minor: security + bug fixes.
+- Previous minor: security fixes only, 6 months after a new minor ships.
+- Deprecations: a tool or input field marked deprecated in a minor must stay for at least one more minor before removal in the next major.
+
+### Pinning
+
+Once on v1.0 you can safely pin with a caret range:
+
+```json
+"@jadenrazo/cloudcost-mcp": "^1.0.0"
+```
+
+This accepts bugfixes, pricing refreshes, and additive features, and will not pull in breaking changes.

package/STABILITY.md

@@ -0,0 +1,71 @@
+# Stability Policy
+
+Starting with v1.0.0, CloudCostMCP follows [Semantic Versioning](https://semver.org/). This document defines the **stable public surface** covered by that guarantee — changes to anything listed here are breaking and require a major version bump.
+
+## Stable surface (SemVer-locked)
+
+### MCP tools
+
+The following 11 tools and their input schemas are locked. Their names, required fields, and the type shape of their output are stable. See `src/tools/*.ts` for the Zod schemas.
+
+| Tool                | Purpose                                                                   |
+| ------------------- | ------------------------------------------------------------------------- |
+| `analyze_terraform` | Parse Terraform HCL and extract a resource inventory                      |
+| `estimate_cost`     | Estimate monthly/yearly cost for a Terraform resource set on one provider |
+| `compare_providers` | Full multi-cloud cost comparison with savings analysis                    |
+| `get_equivalents`   | Map Terraform resource types and instance sizes across providers          |
+| `get_pricing`       | Direct pricing lookup for a service/resource/region                       |
+| `optimize_cost`     | Right-sizing and reserved-pricing recommendations                         |
+| `what_if`           | Scenario cost modeling without modifying source files                     |
+| `analyze_plan`      | Cost-of-change analysis from a Terraform plan JSON                        |
+| `compare_actual`    | `.tfstate` vs planned cost drift detection                                |
+| `price_trends`      | Historical pricing trend query                                            |
+| `detect_anomalies`  | Budget and concentration-risk anomaly detection                           |
+
+### CLI
+
+The `cloudcost-mcp` and `cloudcost` binaries and their documented flags in the README are stable.
+
+### Package entry points
+
+- `main`: `dist/index.js`
+- `types`: `dist/index.d.ts`
+- `bin`: `cloudcost-mcp`, `cloudcost`
+- Node engine: `>=20.0.0`
+
+## Not stable (may change in any release)
+
+- Internal parser implementations under `src/parsers/`
+- Pricing adapter internals under `src/pricing/aws`, `src/pricing/azure`, `src/pricing/gcp`
+- The on-disk SQLite cache schema (cache is rebuilt on upgrade)
+- Bundled fallback pricing tables under `data/`
+- Log line format and log levels
+- Exit codes beyond `0` (success) and `1` (failure)
+- Benchmark scripts and unreleased helper modules
+
+## Change classification
+
+| Change                                           | Bump  |
+| ------------------------------------------------ | ----- |
+| Remove or rename a tool                          | Major |
+| Remove a required input field from a tool schema | Major |
+| Change the type of an existing output field      | Major |
+| Raise the minimum Node.js version                | Major |
+| Add a new tool                                   | Minor |
+| Add an optional input field                      | Minor |
+| Add a new output field                           | Minor |
+| Add a new provider/region/resource               | Minor |
+| Bugfix                                           | Patch |
+| Performance improvement                          | Patch |
+| Pricing data refresh                             | Patch |
+| Dependency bump without API change               | Patch |
+
+## Deprecation
+
+Before a tool or field is removed in a future major, it will be marked deprecated in its description for at least one minor release, with the replacement documented in `CHANGELOG.md`.
+
+## Support policy
+
+- The latest minor line receives security and bug fixes.
+- The previous minor line receives security fixes only, for 6 months after the next minor is released.
+- CVE reports: see `SECURITY.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jadenrazo/cloudcost-mcp",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "MCP server for multi-cloud cost analysis of Terraform, CloudFormation, Pulumi, and Bicep/ARM codebases",
   "type": "module",
   "license": "MIT",
@@ -39,7 +39,10 @@
     "!dist/**/*.map",
     "data",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "STABILITY.md",
+    "MIGRATION.md",
+    "CHANGELOG.md"
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -71,6 +74,12 @@
     "yaml": "^2.8.3",
     "zod": "^3.24.4"
   },
+  "overrides": {
+    "hono": "^4.12.12",
+    "@hono/node-server": "^1.19.13",
+    "path-to-regexp": "^8.4.0",
+    "vite": "^7.3.2"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/better-sqlite3": "^7.6.13",