amplify-monitor

A Rust CLI tool for monitoring AWS Amplify builds and diagnosing failures. Includes a VS Code extension and MCP server for AI assistant integration.

Features

• 📋 List Amplify apps, branches, and jobs
• 🔍 Detect the latest failed build
• 📥 Download and analyze build/deploy logs
• 🩺 Diagnose 20+ common failure patterns
• 🌍 Multi-region support - scan all AWS regions
• 🔄 Cross-account support - AWS profiles for different accounts
• 📤 Output as JSON or human-readable text

Ecosystem

Component	Description
CLI	Core Rust binary for terminal usage
VS Code Extension	Visual interface with tree views
MCP Server	Let Claude/AI assistants diagnose your builds

Installation

From Source

# Clone the repository
git clone https://github.com/saga95/amplify-monitor.git
cd amplify-monitor

# Build release binary
cargo build --release

# Binary is at ./target/release/amplify-monitor

Prerequisites

• Rust 1.70+ (install via rustup)
• AWS credentials with Amplify read access

Configuration

Config File

Create a config file to set defaults and skip repetitive CLI arguments:

# Generate sample config
amplify-monitor init

This creates ~/.amplify-monitor.toml:

# Default app ID (find with `amplify-monitor apps`)
default_app_id = "d1234567890"

# Default branch name
default_branch = "main"

# Default output format: json, json-pretty, or text
default_format = "text"

# AWS region (overrides AWS_REGION env var)
# aws_region = "us-east-1"

With config set, you can simply run:

amplify-monitor diagnose    # Uses defaults from config

AWS Credentials

Set AWS credentials via environment variables:

# Linux/macOS
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_REGION="us-east-1"

# Windows PowerShell
$env:AWS_ACCESS_KEY_ID = "your-access-key"
$env:AWS_SECRET_ACCESS_KEY = "your-secret-key"
$env:AWS_REGION = "us-east-1"

Required IAM Permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "amplify:ListApps",
        "amplify:ListBranches",
        "amplify:ListJobs",
        "amplify:GetJob"
      ],
      "Resource": "*"
    }
  ]
}

Usage

List all apps

amplify-monitor apps

[
  {
    "appId": "d1234567890",
    "name": "my-react-app",
    "repository": "https://github.com/user/my-react-app",
    "defaultDomain": "main.d1234567890.amplifyapp.com"
  }
]

List branches

amplify-monitor branches --app-id d1234567890

List jobs for a branch

amplify-monitor jobs --app-id d1234567890 --branch main

Get latest failed job

amplify-monitor latest-failed --app-id d1234567890 --branch main

Diagnose a failed build

# Diagnose the latest failed job
amplify-monitor diagnose --app-id d1234567890 --branch main

# Diagnose a specific job
amplify-monitor diagnose --app-id d1234567890 --branch main --job-id 123

Example output:

{
  "appId": "d1234567890",
  "branch": "main",
  "jobId": "42",
  "status": "FAILED",
  "issues": [
    {
      "pattern": "npm_ci_failure",
      "rootCause": "npm ci failed - likely due to package-lock.json sync issues",
      "suggestedFixes": [
        "Run 'npm install' locally to regenerate package-lock.json",
        "Commit the updated package-lock.json",
        "Ensure package-lock.json is not in .gitignore"
      ]
    }
  ]
}

Output Formats

# Compact JSON (default, best for piping)
amplify-monitor --format json apps

# Pretty JSON (human-readable)
amplify-monitor --format json-pretty apps

# Text output (human-readable)
amplify-monitor --format text diagnose --app-id d1234567890 --branch main

Detected Failure Patterns

Pattern	Description
lockfile_mismatch	Conflicting lock files (npm/pnpm/yarn)
package_manager_conflict	Multiple package managers detected
node_version_mismatch	Node.js version incompatibility
missing_env_vars	Required environment variables not set
npm_ci_failure	npm ci command failed
pnpm_install_failure	pnpm install failed
yarn_install_failure	yarn install failed
amplify_yml_error	Invalid amplify.yml configuration
out_of_memory	JavaScript heap out of memory
timeout	Build exceeded time limit
artifact_path_error	Build output directory not found
typescript_error	TypeScript compilation failed
eslint_error	ESLint validation failed
module_not_found	Missing npm module
permission_denied	File system permission error
network_error	Network connectivity issue
docker_error	Docker/container build issue
python_error	Python dependency error
nextjs_error	Next.js build failure
vite_error	Vite/Rollup bundling failure

Examples

Quick diagnosis workflow

# 1. Find your app ID
amplify-monitor apps --format text

# 2. Check recent jobs
amplify-monitor jobs --app-id d1234567890 --branch main --format text

# 3. Diagnose the failure
amplify-monitor diagnose --app-id d1234567890 --branch main --format text

Pipe to jq

# Get just the issue patterns
amplify-monitor diagnose --app-id d1234567890 --branch main | jq '.issues[].pattern'

# Count issues
amplify-monitor diagnose --app-id d1234567890 --branch main | jq '.issues | length'

Use in scripts

#!/bin/bash
RESULT=$(amplify-monitor diagnose --app-id $APP_ID --branch main)
ISSUES=$(echo $RESULT | jq '.issues | length')

if [ "$ISSUES" -gt 0 ]; then
  echo "Found $ISSUES issues in build"
  echo $RESULT | jq '.issues[].suggestedFixes[]'
fi

Development

# Run tests
cargo test

# Run with debug logging
RUST_LOG=debug cargo run -- apps

# Check for issues
cargo clippy

# Format code
cargo fmt

CI/CD

This project uses GitHub Actions for:

• CI (.github/workflows/ci.yml): Tests on Linux, Windows, macOS
• Release (.github/workflows/release.yml): Build binaries on tag push

To create a release:

git tag v0.1.0
git push origin v0.1.0

MCP Server (AI Integration)

Let Claude and other AI assistants diagnose your Amplify builds directly!

Quick Setup

cd mcp-server
npm install
npm run build

Claude Desktop Config

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "amplify-monitor": {
      "command": "node",
      "args": ["C:\\path\\to\\amplify-monitor\\mcp-server\\dist\\index.js"]
    }
  }
}

Example Conversation

You: Why did my friday.lk main branch fail?

Claude: I'll diagnose the latest failed build for you.
[Uses amplify_diagnose tool]

I found 2 issues:

1. **Lock File Mismatch**
   Both package-lock.json and pnpm-lock.yaml exist.
   Fix: Remove one and use a consistent package manager.

2. **Node.js Version Conflict**
   Build uses Node 16 but dependencies require 18+.
   Fix: Update amplify.yml to specify Node 18.

See mcp-server/README.md for full documentation.

Roadmap

• Config file support (~/.amplify-monitor.toml)
• GitHub Actions CI
• VS Code extension ✅
• MCP server for AI agent integration ✅
• watch command for polling build status