fix: resolve OTEL collector YAML syntax error and add validation tools

- Fixed syntax error on line 306 of otel-collector.yaml (removed rogue 'z' character)
- Added pre-commit, yamllint, and cfn-lint for automated template validation
- Created validation script compatible with existing git hooks
- Updated README with development validation instructions
- Validation now runs automatically on every commit to prevent deployment failures

Fixes #13

Author: schuettc

.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+# Pre-commit hooks for CloudFormation and YAML validation
+# Run `pre-commit install` to set up the git hook scripts
+# See https://pre-commit.com for more information
+
+repos:
+  # YAML syntax validation
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.33.0
+    hooks:
+      - id: yamllint
+        name: Validate YAML syntax
+        args: ['-d', 'relaxed']
+        files: \.(yaml|yml)$
+        exclude: ^(source/build/|source/dist/)
+
+  # CloudFormation template validation
+  - repo: https://github.com/aws-cloudformation/cfn-lint
+    rev: v0.83.8
+    hooks:
+      - id: cfn-lint
+        name: Validate CloudFormation templates
+        files: deployment/infrastructure/.*\.(yaml|yml)$
+        args: ['--ignore-checks', 'W3002']  # W3002 is for optional resource properties
+
+  # Custom AWS validation (requires AWS credentials)
+  - repo: local
+    hooks:
+      - id: validate-cfn-templates
+        name: Validate CloudFormation with AWS CLI
+        entry: scripts/validate-cloudformation.sh
+        language: script
+        files: deployment/infrastructure/.*\.(yaml|yml)$
+        pass_filenames: true
+        # This hook will only run if AWS credentials are configured
+        # It provides additional validation beyond cfn-lint

README.md

@@ -382,6 +382,42 @@ Detailed setup guides are available for:
 - [Microsoft Entra ID (Azure AD)](/assets/docs/providers/microsoft-entra-id-setup.md)
 - [Auth0](/assets/docs/providers/auth0-setup.md)
 
+## Development
+
+### CloudFormation Template Validation
+
+This project includes automated validation tools that catch CloudFormation and YAML syntax errors before deployment.
+
+#### Setup Validation Tools
+
+```bash
+cd source
+poetry install  # Installs validation dependencies including pre-commit, yamllint, and cfn-lint
+
+# Install pre-commit hooks
+poetry run pre-commit install
+```
+
+#### How It Works
+
+When you commit changes, the following validations run automatically:
+- **YAML validation** checks syntax in all `.yaml` files
+- **CloudFormation validation** checks template structure and properties
+- **AWS CLI validation** validates templates against AWS specifications (if credentials are configured)
+
+The validation automatically catches:
+- YAML syntax errors that would cause deployment failures
+- CloudFormation template structure problems
+- Missing required parameters or invalid resource configurations
+
+#### Manual Validation (Optional)
+
+To run validation without committing:
+```bash
+cd source
+poetry run pre-commit run --all-files
+```
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

deployment/infrastructure/otel-collector.yaml

@@ -303,7 +303,7 @@ Resources:
 
         receivers:
           otlp:
-            protocols:z
+            protocols:
               grpc:
                 endpoint: 0.0.0.0:4317
                 include_metadata: true
@@ -374,43 +374,43 @@ Resources:
               # Core user dimensions
               - dimensions: [[user.id, aws.account_id, OTelLib]]
                 metric_name_selectors: [".*"]
-              
+
               # Team and organization dimensions
               - dimensions: [[department, team.id, cost_center, organization, OTelLib]]
                 metric_name_selectors: [".*"]
               - dimensions: [[department, team.id, OTelLib]]
                 metric_name_selectors: [".*"]
               - dimensions: [[cost_center, organization, OTelLib]]
                 metric_name_selectors: [".*"]
-              
+
               # User + team combinations for filtering
               - dimensions: [[user.id, department, team.id, OTelLib]]
                 metric_name_selectors: [".*"]
               - dimensions: [[user.id, cost_center, OTelLib]]
                 metric_name_selectors: [".*"]
-              
+
               # Model and session tracking
               - dimensions: [[model, department, team.id, OTelLib]]
                 metric_name_selectors: ["claude_code.token.usage", "claude_code.cost.usage"]
               - dimensions: [[session.id, user.id, OTelLib]]
                 metric_name_selectors: ["claude_code.active_time.*"]
-              
+
               # Cost tracking dimensions
               - dimensions: [[cost_center, aws.account_id, OTelLib]]
                 metric_name_selectors: ["claude_code.cost.usage"]
               - dimensions: [[department, cost_center, model, OTelLib]]
                 metric_name_selectors: ["claude_code.cost.usage", "claude_code.token.usage"]
-              
+
               # Location and role based
               - dimensions: [[location, department, OTelLib]]
                 metric_name_selectors: [".*"]
               - dimensions: [[role, team.id, OTelLib]]
                 metric_name_selectors: [".*"]
-              
+
               # Environment tracking
               - dimensions: [[deployment.environment, organization, OTelLib]]
                 metric_name_selectors: [".*"]
-              
+
               # Minimal dimension for overall metrics
               - dimensions: [[OTelLib]]
                 metric_name_selectors: [".*"]

scripts/validate-cloudformation.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# ABOUTME: Validates CloudFormation templates using AWS CLI
+# ABOUTME: Used by pre-commit hooks to ensure templates are valid before committing
+
+set -e
+
+# Color codes for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Check if AWS CLI is installed
+if ! command -v aws &> /dev/null; then
+    echo -e "${YELLOW}⚠️  AWS CLI not found. Skipping AWS validation.${NC}"
+    echo "   Install AWS CLI for complete CloudFormation validation."
+    exit 0
+fi
+
+# Check if AWS credentials are configured
+if ! aws sts get-caller-identity &> /dev/null; then
+    echo -e "${YELLOW}⚠️  AWS credentials not configured. Skipping AWS validation.${NC}"
+    echo "   Configure AWS credentials for complete CloudFormation validation."
+    exit 0
+fi
+
+# Validate each template passed as argument
+for template in "$@"; do
+    # Only validate files in deployment/infrastructure directory
+    if [[ "$template" == *"deployment/infrastructure"* ]]; then
+        echo -n "Validating $template with AWS CLI... "
+        
+        # Create a temporary file for error output
+        ERROR_FILE=$(mktemp)
+        
+        # Use AWS CLI to validate template
+        if aws cloudformation validate-template \
+            --template-body file://"$template" \
+            --region us-east-1 >/dev/null 2>"$ERROR_FILE"; then
+            echo -e "${GREEN}✅${NC}"
+        else
+            echo -e "${RED}❌${NC}"
+            echo -e "${RED}CloudFormation validation failed for $template:${NC}"
+            cat "$ERROR_FILE"
+            rm -f "$ERROR_FILE"
+            exit 1
+        fi
+        
+        rm -f "$ERROR_FILE"
+    fi
+done
+
+echo -e "${GREEN}All CloudFormation templates are valid!${NC}"