gitgreen 0.1.1 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 GitGreen
+
+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,77 +1,241 @@
 # GitGreen CLI
 
-Self-contained carbon calculation CLI for GitLab jobs (no API server). It reuses the same power profiles and budget reporting as the existing implementation, pulls Electricity Maps intensity, and can post Merge Request notes via `CI_JOB_TOKEN`.
+Self-contained carbon calculation CLI for GitLab jobs (no API server). It reuses the same power profiles and budget reporting as the existing implementation, pulls Electricity Maps intensity, and can post Merge Request notes via `CI_JOB_TOKEN`. Works with both GCP and AWS runners.
+
+## Prerequisites
+
+Before installing GitGreen CLI, ensure you have the following installed and configured:
+
+### Required
+
+- **Node.js** (v20 or higher) - [Download](https://nodejs.org/)
+  - Required to run the CLI tool
+  - Check version: `node --version`
+
+- **npm** or **pnpm** - Package manager (comes with Node.js)
+  - This project uses `pnpm@8.15.4` as the package manager
+  - Install pnpm: `npm install -g pnpm`
+
+- **Git** - [Download](https://git-scm.com/)
+  - Required for detecting GitLab project information during initialization
+  - Check version: `git --version`
+
+### Cloud Provider CLIs (Required based on provider)
+
+- **Google Cloud SDK (gcloud CLI)** - [Installation Guide](https://cloud.google.com/sdk/docs/install-sdk)
+  - Required for GCP provider setup and authentication
+  - After installation, authenticate: `gcloud auth login`
+  - Set default project: `gcloud config set project YOUR_PROJECT_ID`
+  - Check version: `gcloud --version`
+
+- **AWS Credentials** - [AWS CLI Installation](https://aws.amazon.com/cli/) (optional, but recommended)
+  - Required for AWS provider (can use environment variables or AWS CLI config)
+  - Configure credentials: `aws configure`
+  - Or set environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
+
+### Optional (but recommended)
+
+- **GitLab CLI (glab)** - [Installation Guide](https://docs.gitlab.com/cli/)
+  - Recommended for easier GitLab authentication and CI/CD variable management
+  - After installation, authenticate: `glab auth login`
+  - Check version: `glab --version`
+  - If not installed, you'll need to provide a GitLab Personal Access Token manually
+
+### API Keys
+
+- **Electricity Maps API Key** - [Get free key](https://api-portal.electricitymaps.com)
+  - Required for carbon intensity data
+  - You'll be prompted for this during `gitgreen init`
 
 ## Install
 - From npm (global CLI):
   ```bash
-  pnpm add -g gitgreen-cli
-  # or: npm install -g gitgreen-cli
+  npm install -g gitgreen
   gitgreen --help
   ```
 
-- From this repo:
-  ```bash
-  # from repo root
-  pnpm -C node-module install
-  # build happens via prepare; dist/ is ready for CI
-  ```
-
-Run tests (pnpm preferred):
+Run tests:
 ```bash
-pnpm -C node-module test
-# or: npm --prefix node-module test
+npm test
 ```
 
 Stress test multiple live configs (build first, real APIs):
 ```bash
-pnpm -C node-module build
-pnpm -C node-module stress
+npm build
+npm stress
 ```
 
 ## Usage
-```bash
-gitgreen \
-  --provider gcp \
-  --machine e2-standard-4 \
-  --region us-central1-a \
-  --duration 1800 \
-  --cpu 55 \
-  --budget 500 \
-  --fail-on-budget \
-  --out-md carbon-report.md \
-  --out-json carbon-report.json \
-  --post-note
-```
 
-### Interactive GitLab setup
+### Initializing a New GitLab Project
+
+To get started with carbon tracking in any GitLab project (any project with a remote pointing to a GitLab instance), run:
+
 ```bash
 # In your repo
 gitgreen init
 ```
-The wizard asks for provider/machine/region, budgets, MR note preference, then offers to append a ready-made job to `.gitlab-ci.yml` and prints the CI/CD variable checklist (ELECTRICITY_MAPS_API_KEY, provider creds, budget flags).
-
-Key environment variables (loaded automatically via dotenv):
-- `ELECTRICITY_MAPS_API_KEY` (required)
-- `ELECTRICITY_MAPS_BASE_URL` (optional, defaults to public endpoint)
-- `GCP_PROJECT_ID` / `GOOGLE_CLOUD_PROJECT` (for GCP metric pull)
-- `AWS_*` credentials (for CloudWatch metric pull)
-- `DATA_DIR` (override bundled data)
-- `DEFAULT_PROVIDER`, `PUE_FALLBACK`, `GITLAB_BASE_URL`
-
-GitLab CI auto-detection uses:
-- `CI_JOB_TOKEN`, `CI_PROJECT_ID`, `CI_JOB_ID`, `CI_PIPELINE_ID`, `CI_MERGE_REQUEST_IID`, `CI_SERVER_URL`
-- `CI_RUNNER_TAGS` (comma/space separated) to infer machine/region and instance IDs
-
-## GitLab snippet
-Add variables `ELECTRICITY_MAPS_API_KEY`, `CARBON_BUDGET` (optional), `FAIL_ON_BUDGET` (true/false). Then call:
-```bash
-./scripts/carbon/install-cli.sh
-./scripts/carbon/run-analysis.sh
+
+The initialization wizard will guide you through the setup process:
+- Configure provider/machine/region settings
+- Set carbon budgets
+- Configure MR note preferences
+- Choose to use an existing runner or spin up a new one with supported providers
+
+After initialization, the wizard will:
+- Append a ready-made job to your `.gitlab-ci.yml`
+- Print the CI/CD variable checklist (ELECTRICITY_MAPS_API_KEY, provider credentials, budget flags)
+
+### How It Works
+
+Once initialized, all subsequent pipelines will run on the configured runner, and their performance will be automatically measured. The carbon tracking is implemented using GitLab CI/CD components as a final step in your pipeline. The carbon tracking job itself is not computationally expensive, so it adds minimal overhead to your CI/CD workflows.
+
+Key environment variables:
+- `ELECTRICITY_MAPS_API_KEY` (required) - Get a free key from https://api-portal.electricitymaps.com
+- `GCP_PROJECT_ID` / `GOOGLE_CLOUD_PROJECT` (required for GCP) - Your GCP project ID
+- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (required for AWS CloudWatch) - Credentials with CloudWatch read access on the runner
+- `AWS_REGION` (for AWS) - Region of the runner EC2 instance
+
+The `gitgreen init` wizard will automatically set all necessary GitLab CI/CD variables for you.
+
+## Providers
+
+GitGreen supports multiple cloud providers:
+
+- **GCP**: Fully wired — the CLI parser expects GCP Monitoring JSON, the GitLab component polls GCE metrics, and `gitgreen init` provisions or reuses GCP runners.
+- **AWS**: CloudWatch-backed — the CLI can pull metrics directly via `--from-cloudwatch`, the GitLab component fetches CloudWatch CPU/RAM data, and `gitgreen init` can configure or provision EC2 runners.
+
+## Architecture
+Runtime flow:
+```
+CPU/RAM timeseries (GCP Monitoring JSON or custom collector)
+        |
+        v
++------------------+    +----------------------------+
+| CLI (gitgreen)   |--->| CarbonCalculator           |
+| - parse metrics  |    | - PowerProfileRepository   |<- machine data in data/*.json
+| - CLI/env opts   |    | - ZoneMapper (region→zone) |<- static + runtime PUE mapping
++------------------+    | - IntensityProvider        |<- Electricity Maps API
+                         +-------------+------------+
+                                       |
+                                       v
+                        +-----------------------------+
+                        | Report formatter            |
+                        | - Markdown/JSON artifacts   |
+                        | - Budget evaluation         |
+                        +-------------+---------------+
+                                       |
+                                       v
+                        +-----------------------------+
+                        | GitLab client (optional)    |
+                        | - MR note via CI_JOB_TOKEN  |
+                        +-----------------------------+
+```
+
+GitLab CI path:
+```
+Pipeline starts → component script fetches CPU/RAM timeseries from GCP Monitoring or AWS CloudWatch
+              → writes JSON files → runs `gitgreen --provider gcp|aws ...`
+              → emits `carbon-report.md` / `carbon-report.json`
+              → optional MR note when CI_JOB_TOKEN is present
 ```
-Artifacts `carbon-report.md` and `carbon-report.json` will be produced; `POST_MR_NOTE=true` will post to the MR when `CI_JOB_TOKEN` is available.
+
+## Adding a provider
+1. Extend `CloudProvider` and the provider guard in `src/index.ts` so the calculator accepts the new key.
+2. Add machine power data (`<provider>_machine_power_profiles.json`) and, if needed, CPU profiles to `data/`, then update `PowerProfileRepository.loadMachineData` to load it.
+3. Map regions to Electricity Maps zones and a PUE default in `ZoneMapper` (or via `data/runtime-pue-mappings.json` for runtime overrides).
+4. Parse that provider's metrics into the `TimeseriesPoint` shape (timestamp + numeric value) alongside RAM size/usage, and update the CLI/init/templates to pull those metrics.
+5. Wire any CI automation (runner tags, MR note flags) to pass the correct provider, machine type, and region strings.
 
 ## Publish
 - Ensure version bump in `package.json`
 - Run `pnpm -C node-module build && pnpm -C node-module test`
 - Publish: `pnpm -C node-module publish --access public`
+
+## FAQ
+
+### Are my API keys and credentials secure?
+
+Yes. GitGreen does not save your keys locally. During `gitgreen init`, all sensitive credentials (API keys, service account keys, AWS credentials) are stored only in GitLab CI/CD variables, which are encrypted and managed by GitLab. The CLI never writes credentials to disk on your local machine.
+
+### Does GitGreen call any third-party APIs?
+
+GitGreen only calls APIs that you explicitly configure and authorize:
+
+- **Electricity Maps API** - For carbon intensity data (requires your API key)
+- **GitLab API** - Only when using `glab` CLI or providing a PAT, to set CI/CD variables
+- **GCP Monitoring API** - To fetch CPU/RAM metrics from your GCP project (requires your service account)
+- **AWS CloudWatch API** - To fetch CPU/RAM metrics from your AWS account (requires your AWS credentials)
+
+GitGreen does not operate any backend services or call any APIs owned by the GitGreen project. All API calls are made directly from your environment or CI/CD pipeline using your credentials.
+
+### How do I know GitGreen won't destroy my `.gitlab-ci.yml` file?
+
+GitGreen takes safety precautions when modifying your `.gitlab-ci.yml`:
+
+1. **Automatic backups** - Before making any changes, GitGreen creates a backup of your existing `.gitlab-ci.yml` file
+2. **Backup location** - The backup path is printed to the console (e.g., `/tmp/gitlab-ci-backup-{timestamp}.yml`)
+3. **Append-only changes** - GitGreen only appends new content to your CI file; it never removes or modifies existing jobs
+4. **Confirmation prompt** - You're asked to confirm before any changes are made
+
+If something goes wrong, you can restore your file from the backup location that was printed.
+
+### Can I use GitGreen without the `init` wizard?
+
+Yes. You can configure GitGreen manually by:
+
+1. Setting the required CI/CD variables in your GitLab project settings
+2. Adding the GitLab CI/CD component to your `.gitlab-ci.yml` manually
+3. Running `gitgreen` directly with command-line options instead of using the component
+
+The `init` wizard is a convenience tool, but all functionality is available through manual configuration.
+
+### What data does GitGreen collect?
+
+GitGreen only collects:
+
+- **CPU and RAM usage metrics** from your cloud provider (GCP Monitoring or AWS CloudWatch)
+- **Pipeline metadata** (start/end times) from GitLab CI/CD environment variables
+
+GitGreen does not collect any personal information, code, or data from your repositories. All calculations happen locally in your CI/CD pipeline.
+
+### Can I run GitGreen locally for testing?
+
+Yes. You can run `gitgreen` directly with your own metrics files:
+
+**GCP example:**
+```bash
+gitgreen --provider gcp \
+  --machine e2-standard-4 \
+  --region us-central1-a \
+  --cpu-timeseries cpu.json \
+  --ram-used-timeseries ram-used.json \
+  --ram-size-timeseries ram-size.json \
+  --out-md report.md
+```
+
+**AWS example:**
+```bash
+gitgreen --provider aws \
+  --machine t3.medium \
+  --region us-east-1 \
+  --cpu-timeseries cpu.json \
+  --ram-used-timeseries ram-used.json \
+  --ram-size-timeseries ram-size.json \
+  --out-md report.md
+```
+
+Or use `--from-cloudwatch` to fetch metrics directly from AWS CloudWatch:
+```bash
+gitgreen --provider aws \
+  --machine t3.medium \
+  --region us-east-1 \
+  --from-cloudwatch \
+  --out-md report.md
+```
+
+This is useful for testing before integrating into your CI/CD pipeline.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

package/dist/cli.js

@@ -8,47 +8,217 @@ const fs_1 = __importDefault(require("fs"));
 const commander_1 = require("commander");
 const kleur_1 = require("kleur");
 const asciichart_1 = __importDefault(require("asciichart"));
+const config_1 = require("./config");
 const index_1 = require("./index");
 const init_1 = require("./init");
+const cloudwatch_1 = require("./lib/aws/cloudwatch");
+const power_profile_repository_1 = require("./lib/carbon/power-profile-repository");
 const program = new commander_1.Command();
-function parseGcpTimeseries(filePath) {
+const toIsoTimestamp = (input) => {
+    if (input instanceof Date) {
+        return Number.isNaN(input.getTime()) ? undefined : input.toISOString();
+    }
+    if (typeof input === 'string' || typeof input === 'number') {
+        const date = new Date(input);
+        return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+    }
+    return undefined;
+};
+const toNumericValue = (input) => {
+    if (typeof input === 'number') {
+        return Number.isFinite(input) ? input : undefined;
+    }
+    if (typeof input === 'string') {
+        const parsed = Number(input);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+};
+const formatErrorMessage = (value) => {
+    if (value instanceof Error)
+        return value.message;
+    if (value === null || value === undefined)
+        return 'Unknown error';
+    return String(value);
+};
+const parseGcpTimeseries = (raw) => {
+    const points = [];
+    const response = raw;
+    const timeSeries = response.timeSeries;
+    if (!Array.isArray(timeSeries))
+        return points;
+    for (const ts of timeSeries) {
+        const series = ts;
+        if (!Array.isArray(series.points))
+            continue;
+        for (const point of series.points) {
+            const timestamp = toIsoTimestamp(point.interval?.endTime || point.interval?.startTime);
+            const value = point.value?.doubleValue !== undefined
+                ? toNumericValue(point.value.doubleValue)
+                : toNumericValue(point.value?.int64Value);
+            if (timestamp && value !== undefined)
+                points.push({ timestamp, value });
+        }
+    }
+    return points;
+};
+const parseCloudWatchMetricData = (raw) => {
+    const data = raw.MetricDataResults || raw.metricDataResults;
+    const results = Array.isArray(data) ? data : [];
+    if (!results.length)
+        return [];
+    const first = results[0];
+    const timestamps = Array.isArray(first?.Timestamps) ? first.Timestamps : [];
+    const values = Array.isArray(first?.Values) ? first.Values : [];
+    const len = Math.min(timestamps.length, values.length);
+    const points = [];
+    for (let i = 0; i < len; i++) {
+        const timestamp = toIsoTimestamp(timestamps[i]);
+        const value = toNumericValue(values[i]);
+        if (timestamp && value !== undefined) {
+            points.push({ timestamp, value });
+        }
+    }
+    return points;
+};
+const parseTimeseriesFile = (filePath) => {
     const raw = JSON.parse(fs_1.default.readFileSync(filePath, 'utf8'));
+    const gcp = parseGcpTimeseries(raw);
+    if (gcp.length)
+        return gcp;
+    const cw = parseCloudWatchMetricData(raw);
+    if (cw.length)
+        return cw;
+    if (Array.isArray(raw)) {
+        const cwFromArray = parseCloudWatchMetricData({ MetricDataResults: raw });
+        if (cwFromArray.length)
+            return cwFromArray;
+        const legacy = parseLegacyTimeseries(raw);
+        if (legacy.length)
+            return legacy;
+    }
+    const datapointResponse = raw;
+    if (Array.isArray(datapointResponse.Datapoints)) {
+        const datapointSeries = convertCloudWatchDatapoints(datapointResponse.Datapoints);
+        if (datapointSeries.length)
+            return datapointSeries;
+    }
+    return [];
+};
+const parseLegacyTimeseries = (entries) => {
     const points = [];
-    for (const ts of raw.timeSeries || []) {
-        for (const p of ts.points || []) {
-            const timestamp = p.interval?.endTime || p.interval?.startTime;
-            let value;
-            if (p.value?.doubleValue !== undefined) {
-                value = p.value.doubleValue;
-            }
-            else if (p.value?.int64Value !== undefined) {
-                value = Number(p.value.int64Value);
-            }
-            else {
-                continue;
-            }
+    for (const entry of entries) {
+        const timestamp = toIsoTimestamp((entry.timestamp ?? entry.Timestamp));
+        const value = toNumericValue((entry.value ?? entry.Value));
+        if (timestamp && value !== undefined) {
             points.push({ timestamp, value });
         }
     }
     return points;
-}
+};
+const convertCloudWatchDatapoints = (entries) => {
+    const points = [];
+    for (const entry of entries) {
+        const timestamp = toIsoTimestamp(entry.Timestamp);
+        const value = toNumericValue((entry.Average ?? entry.Maximum ?? entry.Minimum ?? entry.Sum));
+        if (timestamp && value !== undefined) {
+            points.push({ timestamp, value });
+        }
+    }
+    return points;
+};
 const runCalculate = async (opts) => {
     const gitlabDisabled = opts.gitlab === false;
-    if (!opts.cpuTimeseries || !opts.ramUsedTimeseries || !opts.ramSizeTimeseries) {
-        console.error((0, kleur_1.red)('Error: --cpu-timeseries, --ram-used-timeseries, and --ram-size-timeseries are required'));
+    const provider = (opts.provider || config_1.config.defaultProvider);
+    const regionInput = opts.region || opts.awsRegion;
+    const awsEnvRegion = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION;
+    const calculationRegion = provider === 'aws' ? (regionInput || awsEnvRegion) : regionInput;
+    if (!opts.machine) {
+        console.error((0, kleur_1.red)('Error: --machine is required'));
+        process.exitCode = 1;
+        return;
+    }
+    if (!calculationRegion) {
+        console.error((0, kleur_1.red)('Error: --region (or --aws-region) is required'));
         process.exitCode = 1;
         return;
     }
-    const cpuTimeseries = parseGcpTimeseries(opts.cpuTimeseries);
-    const ramUsedTimeseries = parseGcpTimeseries(opts.ramUsedTimeseries);
-    const ramSizeTimeseries = parseGcpTimeseries(opts.ramSizeTimeseries);
+    let cpuTimeseries = [];
+    let ramUsedTimeseries = [];
+    let ramSizeTimeseries = [];
+    const timeseriesProvided = Boolean(opts.cpuTimeseries && opts.ramUsedTimeseries && opts.ramSizeTimeseries);
+    const shouldFetchCloudWatch = provider === 'aws' && (opts.fromCloudwatch || (!timeseriesProvided && opts.awsInstanceId));
+    if (shouldFetchCloudWatch) {
+        const instanceId = opts.awsInstanceId;
+        const resolvedRegion = calculationRegion || awsEnvRegion;
+        if (!resolvedRegion || !instanceId) {
+            console.error((0, kleur_1.red)('Error: --aws-instance-id and --region/--aws-region are required for AWS provider'));
+            process.exitCode = 1;
+            return;
+        }
+        const awsInstanceId = instanceId;
+        const awsRegionValue = resolvedRegion;
+        const startTime = opts.awsStartTime
+            ? new Date(opts.awsStartTime)
+            : process.env.CI_PIPELINE_CREATED_AT
+                ? new Date(process.env.CI_PIPELINE_CREATED_AT)
+                : new Date(Date.now() - 60 * 60 * 1000);
+        const endTime = opts.awsEndTime ? new Date(opts.awsEndTime) : new Date();
+        const periodSeconds = opts.awsPeriod ? Number(opts.awsPeriod) : 60;
+        let memoryBytesFallback;
+        try {
+            const repo = new power_profile_repository_1.PowerProfileRepository(config_1.config.dataDir);
+            const profile = await repo.getMachineProfile('aws', opts.machine);
+            if (profile?.memoryGb) {
+                memoryBytesFallback = profile.memoryGb * 1024 * 1024 * 1024;
+            }
+        }
+        catch { }
+        try {
+            const cw = await (0, cloudwatch_1.fetchCloudWatchTimeseries)({
+                region: awsRegionValue,
+                instanceId: awsInstanceId,
+                startTime,
+                endTime,
+                periodSeconds,
+                memoryBytesFallback
+            });
+            cpuTimeseries = cw.cpuUtilization;
+            ramUsedTimeseries = cw.ramUsed;
+            ramSizeTimeseries = cw.ramTotal;
+            if (!ramSizeTimeseries.length && memoryBytesFallback) {
+                const ts = ramUsedTimeseries[0]?.timestamp || new Date().toISOString();
+                ramSizeTimeseries = [{ timestamp: ts, value: memoryBytesFallback }];
+            }
+        }
+        catch (errorValue) {
+            console.error((0, kleur_1.red)('Error fetching CloudWatch metrics:'), formatErrorMessage(errorValue));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else {
+        if (!timeseriesProvided) {
+            console.error((0, kleur_1.red)('Error: --cpu-timeseries, --ram-used-timeseries, and --ram-size-timeseries are required'));
+            process.exitCode = 1;
+            return;
+        }
+        cpuTimeseries = parseTimeseriesFile(opts.cpuTimeseries);
+        ramUsedTimeseries = parseTimeseriesFile(opts.ramUsedTimeseries);
+        ramSizeTimeseries = parseTimeseriesFile(opts.ramSizeTimeseries);
+    }
     console.log((0, kleur_1.gray)(`Loaded ${cpuTimeseries.length} CPU points, ${ramUsedTimeseries.length} RAM points`));
     // Sort by timestamp for charts
     const cpuSorted = [...cpuTimeseries].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
     const ramSorted = [...ramUsedTimeseries].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
     const ramSizeSorted = [...ramSizeTimeseries].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
     // CPU chart (only if more than 1 point)
-    const cpuValues = cpuSorted.map(p => p.value * 100);
+    const cpuValues = cpuSorted.map(p => {
+        if (provider === 'aws') {
+            return p.value <= 1 ? p.value * 100 : p.value;
+        }
+        return p.value * 100;
+    });
     if (cpuValues.length > 1) {
         console.log((0, kleur_1.bold)('\nCPU Utilization (%)'));
         console.log(asciichart_1.default.plot(cpuValues, { height: 8, format: (x) => x.toFixed(1).padStart(6) }));
@@ -62,9 +232,9 @@ const runCalculate = async (opts) => {
     }
     try {
         const { result, budget, markdown } = await (0, index_1.calculate)({
-            provider: opts.provider,
+            provider,
             machineType: opts.machine,
-            region: opts.region,
+            region: calculationRegion,
             cpuTimeseries,
             ramUsedTimeseries,
             ramSizeTimeseries,
@@ -102,20 +272,26 @@ const runCalculate = async (opts) => {
             process.exitCode = 1;
         }
     }
-    catch (err) {
-        console.error((0, kleur_1.red)('Error:'), err?.message || err);
+    catch (errorValue) {
+        console.error((0, kleur_1.red)('Error:'), formatErrorMessage(errorValue));
         process.exitCode = 1;
     }
 };
 program
     .name('gitgreen')
     .description('GitGreen carbon calculator using real timeseries metrics')
-    .option('-p, --provider <provider>', 'Cloud provider (gcp)')
+    .option('-p, --provider <provider>', 'Cloud provider (gcp|aws)', config_1.config.defaultProvider)
     .option('-m, --machine <type>', 'Machine type (e.g., e2-standard-4)')
-    .option('-r, --region <region>', 'Region/zone (e.g., us-central1-a)')
-    .option('--cpu-timeseries <path>', 'Path to CPU timeseries JSON (GCP Monitoring format)')
+    .option('-r, --region <region>', 'Region/zone (e.g., us-central1-a or us-east-1)')
+    .option('--cpu-timeseries <path>', 'Path to CPU timeseries JSON (GCP Monitoring or CloudWatch)')
     .option('--ram-used-timeseries <path>', 'Path to RAM used timeseries JSON')
     .option('--ram-size-timeseries <path>', 'Path to RAM size timeseries JSON')
+    .option('--aws-instance-id <id>', 'AWS EC2 instance ID (for CloudWatch fetch)')
+    .option('--aws-region <region>', 'AWS region (overrides --region)')
+    .option('--aws-start-time <iso>', 'Custom start time (ISO) for CloudWatch metrics')
+    .option('--aws-end-time <iso>', 'Custom end time (ISO) for CloudWatch metrics')
+    .option('--aws-period <seconds>', 'CloudWatch metric period in seconds', v => Number(v))
+    .option('--from-cloudwatch', 'Fetch CPU/RAM metrics from CloudWatch (AWS only)')
     .option('--budget <grams>', 'Carbon budget in grams CO2e', v => Number(v))
     .option('--fail-on-budget', 'Exit non-zero when budget exceeded')
     .option('--out-md <path>', 'Write markdown report')