cloud-cost-cli 0.1.0

package/docs/RELEASE.md

@@ -0,0 +1,143 @@
+# Release Process
+
+This document describes how to publish a new version of cloud-cost-cli.
+
+## Prerequisites
+
+### 1. NPM Granular Access Token
+
+npm now uses "Granular Access Tokens" instead of automation tokens.
+
+**Create the token:**
+1. Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
+2. Click **"Generate New Token"** → **"Granular Access Token"**
+3. Configure the token:
+   - **Token name**: `cloud-cost-cli-publish` (or any name)
+   - **Expiration**: 1 year (or No expiration)
+   - **Packages and scopes**: Select packages → Choose `cloud-cost-cli`
+   - **Permissions**: Read and write
+4. Click **"Generate Token"**
+5. Copy the token (starts with `npm_...`)
+
+### 2. Add Token to GitHub Secrets
+
+1. Go to https://github.com/vuhp/cloud-cost-cli/settings/secrets/actions
+2. Click **"New repository secret"**
+3. Name: `NPM_TOKEN`
+4. Value: (paste the `npm_...` token)
+5. Click **"Add secret"**
+
+## Steps to Release
+
+### 1. Update Version
+
+```bash
+# Bump version (choose one)
+npm version patch   # 0.1.0 → 0.1.1 (bug fixes)
+npm version minor   # 0.1.0 → 0.2.0 (new features)
+npm version major   # 0.1.0 → 1.0.0 (breaking changes)
+
+# Push version commit and tag
+git push && git push --tags
+```
+
+### 2. Create GitHub Release
+
+**Option A: Via GitHub UI**
+1. Go to https://github.com/vuhp/cloud-cost-cli/releases/new
+2. Choose the version tag (e.g., `v0.1.0`)
+3. Title: `v0.1.0 - Initial Release`
+4. Description: Add release notes (features, fixes, breaking changes)
+5. Click **Publish release**
+
+**Option B: Via GitHub CLI**
+```bash
+gh release create v0.1.0 \
+  --title "v0.1.0 - Initial Release" \
+  --notes "First public release with AWS support"
+```
+
+### 3. Automated Publishing
+
+Once you publish the GitHub release:
+- GitHub Actions workflow triggers automatically
+- Builds the TypeScript code
+- Publishes to npm with provenance
+- Package is live at https://www.npmjs.com/package/cloud-cost-cli
+
+### 4. Verify
+
+```bash
+# Check npm
+npm view cloud-cost-cli
+
+# Test installation
+npx cloud-cost-cli@latest --version
+```
+
+## Release Notes Template
+
+```markdown
+## What's New
+
+### Features
+- ✨ Add XYZ analyzer
+- 🚀 Improve performance by 2x
+
+### Bug Fixes
+- 🐛 Fix region handling for profiles
+- 🐛 Correct cost calculation for RDS
+
+### Documentation
+- 📝 Add examples for GCP
+- 📝 Update IAM policy
+
+### Breaking Changes
+- ⚠️ Rename `--days` to `--period`
+
+## Installation
+
+\`\`\`bash
+npm install -g cloud-cost-cli
+# or
+npx cloud-cost-cli scan
+\`\`\`
+
+**Full Changelog**: https://github.com/vuhp/cloud-cost-cli/compare/v0.0.9...v0.1.0
+```
+
+## Rollback
+
+If something goes wrong:
+
+```bash
+# Deprecate the broken version
+npm deprecate cloud-cost-cli@0.1.0 "Broken release, use 0.1.1"
+
+# Publish a patch
+npm version patch
+git push && git push --tags
+# Then create new GitHub release
+```
+
+## Manual Publishing (Emergency Only)
+
+If GitHub Actions fails:
+
+```bash
+npm run build
+npm login
+npm publish --access public
+```
+
+## Checklist
+
+Before releasing:
+- [ ] All tests pass
+- [ ] Version bumped in package.json
+- [ ] CHANGELOG.md updated
+- [ ] README.md reflects new features
+- [ ] Git tag created
+- [ ] GitHub release published
+- [ ] npm package verified
+- [ ] Announcement posted (Twitter, HN, etc.)

package/docs/contributing.md

@@ -0,0 +1,201 @@
+# Contributing to Cloud Cost CLI
+
+Thank you for your interest in contributing! This project welcomes contributions of all kinds.
+
+## Ways to Contribute
+
+- 🐛 Report bugs or issues
+- 💡 Suggest new features or analyzers
+- 📝 Improve documentation
+- 🧪 Add tests
+- 💻 Submit code improvements or new cloud providers
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js >= 18
+- Git
+- AWS account (for testing)
+
+### Clone and Install
+
+```bash
+git clone https://github.com/vuhp/cloud-cost-cli.git
+cd cloud-cost-cli
+npm install
+```
+
+### Run Locally
+
+```bash
+npm run dev -- scan --profile your-aws-profile
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+Output will be in `dist/` directory.
+
+### Run Tests
+
+```bash
+npm test
+```
+
+---
+
+## Project Structure
+
+```
+cloud-cost-cli/
+├── bin/                     # CLI entry point
+├── src/
+│   ├── commands/            # Command implementations (scan, etc.)
+│   ├── providers/           # Cloud provider integrations
+│   │   └── aws/             # AWS-specific analyzers
+│   ├── analyzers/           # Shared analysis logic
+│   ├── reporters/           # Output formatters (table, JSON, markdown)
+│   ├── types/               # TypeScript type definitions
+│   └── utils/               # Helper functions
+├── docs/                    # Documentation
+└── tests/                   # Unit and integration tests
+```
+
+---
+
+## Adding a New Analyzer
+
+Example: Add a Lambda cost analyzer for AWS.
+
+### 1. Create analyzer file
+
+`src/providers/aws/lambda.ts`
+
+```typescript
+import { AWSClient } from './client';
+import { SavingsOpportunity } from '../../types';
+
+export async function analyzeLambdaFunctions(
+  client: AWSClient
+): Promise<SavingsOpportunity[]> {
+  // Implementation here
+  return [];
+}
+```
+
+### 2. Update scan command
+
+`src/commands/scan.ts`
+
+```typescript
+import { analyzeLambdaFunctions } from '../providers/aws/lambda';
+
+// In scanCommand function, add:
+const lambdaOpportunities = await analyzeLambdaFunctions(client);
+```
+
+### 3. Add tests
+
+`tests/unit/providers/aws/lambda.test.ts`
+
+### 4. Update README
+
+Document the new analyzer and what it checks.
+
+---
+
+## Adding a New Cloud Provider
+
+Example: Add GCP support.
+
+### 1. Create provider directory
+
+```
+src/providers/gcp/
+├── client.ts
+├── compute.ts
+├── storage.ts
+└── ...
+```
+
+### 2. Implement analyzers
+
+Follow the same pattern as AWS analyzers.
+
+### 3. Update scan command
+
+Add GCP-specific logic to `src/commands/scan.ts`.
+
+### 4. Update CLI options
+
+Add `gcp` to `--provider` flag in `bin/cloud-cost-cli.ts`.
+
+---
+
+## Code Style
+
+- **TypeScript**: Use strict mode, explicit types
+- **Formatting**: Run `npm run format` before committing
+- **Linting**: Run `npm run lint` to catch issues
+- **Naming**: Use descriptive variable and function names
+
+---
+
+## Commit Messages
+
+Follow conventional commits:
+
+- `feat: add Lambda analyzer`
+- `fix: correct RDS cost calculation`
+- `docs: update installation guide`
+- `test: add EBS analyzer tests`
+- `chore: update dependencies`
+
+---
+
+## Pull Request Process
+
+1. **Fork** the repository
+2. **Create a branch**: `git checkout -b feature/my-feature`
+3. **Make changes** and commit with clear messages
+4. **Test** locally: `npm run build && npm test`
+5. **Push** to your fork: `git push origin feature/my-feature`
+6. **Open a PR** with:
+   - Clear description of changes
+   - Screenshots (if UI-related)
+   - Test results
+
+---
+
+## Reporting Issues
+
+When reporting bugs, please include:
+
+- CLI version (`cloud-cost-cli --version`)
+- Node.js version (`node --version`)
+- Cloud provider and region
+- Command you ran
+- Full error message
+- Expected vs actual behavior
+
+---
+
+## Questions?
+
+- Open a discussion: https://github.com/vuhp/cloud-cost-cli/discussions
+- Join Discord: (link if available)
+- Email: vuhuuphuong@gmail.com
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+Thank you for making cloud cost optimization better for everyone! 🚀

package/docs/iam-policy.json

@@ -0,0 +1,25 @@
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "CloudCostCLIReadOnly",
+      "Effect": "Allow",
+      "Action": [
+        "ec2:DescribeInstances",
+        "ec2:DescribeVolumes",
+        "ec2:DescribeAddresses",
+        "ec2:DescribeRegions",
+        "rds:DescribeDBInstances",
+        "s3:ListAllMyBuckets",
+        "s3:GetBucketLocation",
+        "s3:GetBucketLifecycleConfiguration",
+        "elasticloadbalancing:DescribeLoadBalancers",
+        "elasticloadbalancing:DescribeTargetGroups",
+        "elasticloadbalancing:DescribeTargetHealth",
+        "cloudwatch:GetMetricStatistics",
+        "ce:GetCostAndUsage"
+      ],
+      "Resource": "*"
+    }
+  ]
+}

package/docs/installation.md

@@ -0,0 +1,208 @@
+# Cloud Cost CLI - Installation & Usage
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js >= 18
+- AWS account with configured credentials
+- IAM permissions (see [iam-policy.json](./iam-policy.json))
+
+### Installation
+
+**Option 1: npm (recommended)**
+
+```bash
+npm install -g cloud-cost-cli
+```
+
+**Option 2: npx (no install)**
+
+```bash
+npx cloud-cost-cli scan
+```
+
+**Option 3: Clone and run locally**
+
+```bash
+git clone https://github.com/vuhp/cloud-cost-cli.git
+cd cloud-cost-cli
+npm install
+npm run dev -- scan
+```
+
+---
+
+## AWS Credentials Setup
+
+The CLI uses standard AWS credential resolution. Choose one method:
+
+### Method 1: AWS CLI (easiest)
+
+```bash
+aws configure
+```
+
+Enter your AWS Access Key ID, Secret Access Key, and default region.
+
+### Method 2: Environment variables
+
+```bash
+export AWS_ACCESS_KEY_ID="your-access-key"
+export AWS_SECRET_ACCESS_KEY="your-secret-key"
+export AWS_DEFAULT_REGION="us-east-1"
+```
+
+### Method 3: Named profile
+
+```bash
+# In ~/.aws/credentials:
+[production]
+aws_access_key_id = your-access-key
+aws_secret_access_key = your-secret-key
+
+# Use with CLI:
+cloud-cost-cli scan --profile production
+```
+
+---
+
+## IAM Permissions
+
+Create an IAM user or role with the following policy for read-only access:
+
+[**View full IAM policy**](./iam-policy.json)
+
+**Summary of required permissions:**
+- EC2: DescribeInstances, DescribeVolumes, DescribeAddresses
+- RDS: DescribeDBInstances
+- S3: ListAllMyBuckets, GetBucketLifecycleConfiguration
+- ELB: DescribeLoadBalancers, DescribeTargetGroups, DescribeTargetHealth
+- CloudWatch: GetMetricStatistics
+- Cost Explorer: GetCostAndUsage
+
+---
+
+## Usage Examples
+
+### Basic scan (default region)
+
+```bash
+cloud-cost-cli scan
+```
+
+### Scan specific region
+
+```bash
+cloud-cost-cli scan --region us-west-2
+```
+
+### Show top 10 opportunities
+
+```bash
+cloud-cost-cli scan --top 10
+```
+
+### JSON output (for scripting)
+
+```bash
+cloud-cost-cli scan --output json > report.json
+```
+
+### Filter by minimum savings
+
+```bash
+cloud-cost-cli scan --min-savings 50
+```
+
+Only show opportunities that save >= $50/month.
+
+### Custom analysis period
+
+```bash
+cloud-cost-cli scan --days 60
+```
+
+Analyze usage over the last 60 days instead of default 30.
+
+### Use with specific AWS profile
+
+```bash
+cloud-cost-cli scan --profile production
+```
+
+---
+
+## Sample Output
+
+```
+Cloud Cost Optimization Report
+Provider: aws | Region: us-east-1 | Account: 123456789012
+Analyzed: 2026-01-01 to 2026-01-31
+
+Top 5 Savings Opportunities (est. $1,245.00/month):
+
+┌───┬──────┬─────────────────────────┬──────────────────────────────────────────────────┬─────────────┐
+│ # │ Type │ Resource ID             │ Recommendation                                   │ Savings/mo  │
+├───┼──────┼─────────────────────────┼──────────────────────────────────────────────────┼─────────────┤
+│ 1 │ S3   │ logs-bucket-2023        │ Enable lifecycle policy (Intelligent-Tiering or… │ $938.00     │
+│ 2 │ RDS  │ mydb-production         │ Downsize to db.t3.large (avg CPU: 15.0%, avg c… │ $180.00     │
+│ 3 │ EC2  │ i-0abc123def456         │ Stop instance or downsize to t3.small (avg CPU:… │ $65.00      │
+│ 4 │ EBS  │ vol-0xyz789abc          │ Snapshot and delete, or delete if redundant (ag… │ $40.00      │
+│ 5 │ ELB  │ my-old-alb              │ Delete unused load balancer (no active targets)  │ $22.00      │
+└───┴──────┴─────────────────────────┴──────────────────────────────────────────────────┴─────────────┘
+
+Total potential savings: $1,245.00/month ($14,940.00/year)
+
+Summary: 42 resources analyzed | 3 idle | 2 oversized | 5 unused
+```
+
+---
+
+## Troubleshooting
+
+### Error: AWS credentials not found
+
+**Solution:** Run `aws configure` or set environment variables as shown above.
+
+### Error: Access Denied
+
+**Solution:** Ensure your IAM user/role has the required read-only permissions. See [iam-policy.json](./iam-policy.json).
+
+### Error: Region not enabled
+
+**Solution:** The specified region is not enabled in your AWS account. Try a different region or enable it in the AWS Console.
+
+### No opportunities found
+
+**Possible reasons:**
+- Your account is already well-optimized!
+- Analysis period might be too short (try `--days 60`)
+- Minimum savings filter is too high (remove `--min-savings` or lower the threshold)
+
+---
+
+## CI/CD Integration
+
+Use the CLI in your CI pipeline to catch cost issues early:
+
+```bash
+# In GitHub Actions, GitLab CI, etc.
+npx cloud-cost-cli scan --output json --min-savings 100 > cost-report.json
+
+# Fail the build if savings exceed threshold
+SAVINGS=$(jq '.totalPotentialSavings' cost-report.json)
+if (( $(echo "$SAVINGS > 500" | bc -l) )); then
+  echo "WARNING: Potential savings of \$${SAVINGS}/month detected!"
+  exit 1
+fi
+```
+
+---
+
+## Next Steps
+
+- Star the repo: https://github.com/vuhp/cloud-cost-cli
+- Sponsor the project: https://github.com/sponsors/vuhp
+- Report issues: https://github.com/vuhp/cloud-cost-cli/issues
+- Contribute: https://github.com/vuhp/cloud-cost-cli/pulls

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "cloud-cost-cli",
+  "version": "0.1.0",
+  "description": "Optimize your cloud spend in seconds",
+  "main": "dist/index.js",
+  "bin": {
+    "cloud-cost-cli": "dist/bin/cloud-cost-cli.js"
+  },
+  "scripts": {
+    "dev": "tsx bin/cloud-cost-cli.ts",
+    "build": "tsc",
+    "test": "vitest",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts"
+  },
+  "keywords": [
+    "cloud",
+    "aws",
+    "cost",
+    "optimization",
+    "cli",
+    "finops",
+    "cost-optimization",
+    "aws-cli",
+    "devops",
+    "cloud-cost"
+  ],
+  "author": "Phuong Vu <vuhuuphuong@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vuhp/cloud-cost-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vuhp/cloud-cost-cli/issues"
+  },
+  "homepage": "https://github.com/vuhp/cloud-cost-cli#readme",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-cloudwatch": "^3.712.0",
+    "@aws-sdk/client-cost-explorer": "^3.712.0",
+    "@aws-sdk/client-ec2": "^3.712.0",
+    "@aws-sdk/client-elastic-load-balancing-v2": "^3.712.0",
+    "@aws-sdk/client-rds": "^3.712.0",
+    "@aws-sdk/client-s3": "^3.712.0",
+    "@aws-sdk/credential-providers": "^3.712.0",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "dayjs": "^1.11.13",
+    "ini": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/ini": "^4.1.1",
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.19.1",
+    "@typescript-eslint/parser": "^8.19.1",
+    "eslint": "^8.57.1",
+    "prettier": "^3.4.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^1.6.0"
+  }
+}