@friggframework/devtools 2.0.0-next.40 → 2.0.0-next.42

package/infrastructure/CLAUDE.md

@@ -0,0 +1,481 @@
+# CLAUDE.md - Frigg Infrastructure as Code
+
+This file provides guidance to Claude Code when working with the Frigg Framework's infrastructure system in `packages/devtools/infrastructure/`.
+
+## Critical Context (Read First)
+
+- **Package Purpose**: Infrastructure-as-code templates and AWS resource discovery for Frigg serverless applications
+- **Core Architecture**: AWS-native infrastructure with CloudFormation, serverless framework integration, automatic resource discovery
+- **Key Components**: Serverless template generator, AWS resource discovery, IAM policy generator, deployment automation
+- **Security Model**: VPC deployment, KMS encryption, IAM least-privilege, SSM Parameter Store integration
+- **Deployment Phases**: Phase 1-2 (basic), Phase 3 (enhanced monitoring, CDN, CI/CD pipelines)  
+- **DO NOT**: Hardcode AWS resource IDs, bypass security configurations, create infrastructure outside CloudFormation
+
+## Infrastructure System Architecture
+
+### Core Infrastructure Generator (`serverless-template.js:1-50940`)
+
+**Purpose**: Generates complete serverless.yml configurations with AWS resource discovery integration
+
+**Key Responsibilities**:
+- **Template Generation**: Creates serverless framework configuration from app definition
+- **Resource Discovery Integration**: Automatically discovers and configures AWS resources
+- **Environment Variable Management**: Handles reserved AWS variables and user-defined variables
+- **Module Discovery**: Finds and integrates Node.js modules and dependencies
+- **VPC Configuration**: Configures Lambda functions for private subnet deployment
+- **KMS Integration**: Sets up field-level encryption with customer-managed keys
+
+**App Definition Structure**:
+```javascript
+const AppDefinition = {
+    name: 'my-frigg-app',
+    provider: 'aws',
+    
+    // VPC Configuration
+    vpc: {
+        enable: true,                    // Enable VPC deployment
+        createNew: false,               // Use existing VPC (default)
+        securityGroupIds: [...],        // Optional custom security groups
+        subnetIds: [...],              // Optional custom subnets
+        enableVPCEndpoints: true       // Create VPC endpoints for AWS services
+    },
+    
+    // Encryption Configuration  
+    encryption: {
+        useDefaultKMSForFieldLevelEncryption: true
+    },
+    
+    // SSM Parameter Store
+    ssm: {
+        enable: true
+    },
+    
+    // Environment Variables (serverless-template.js:24-79)
+    environment: {
+        MY_VAR: true,                   // Creates ${env:MY_VAR, ''} reference
+        AWS_REGION: true               // Skipped - reserved AWS variable
+    },
+    
+    // WebSocket Support (Phase 3)
+    websockets: {
+        enable: true
+    },
+    
+    // Integration Definitions
+    integrations: [
+        { Definition: { name: 'hubspot' } },
+        { Definition: { name: 'salesforce' } }
+    ]
+};
+```
+
+### AWS Resource Discovery (`aws-discovery.js:27-550`)
+
+**Purpose**: Automatically discovers existing AWS resources for serverless deployment
+
+**Discovery Capabilities**:
+- **VPC Discovery**: Find default VPC and associated resources
+- **Subnet Discovery**: Identify private subnets for Lambda deployment
+- **Security Group Discovery**: Locate default security groups
+- **KMS Key Discovery**: Find customer-managed KMS keys for encryption
+- **Route Table Discovery**: Map route tables for VPC endpoints
+- **Account Information**: Get AWS account ID and region details
+
+**Core Discovery Methods**:
+```javascript
+const discovery = new AWSDiscovery('us-east-1');
+
+// VPC and Networking
+const vpcId = await discovery.findDefaultVpc();
+const subnets = await discovery.findPrivateSubnets(vpcId);
+const securityGroups = await discovery.findDefaultSecurityGroup(vpcId);
+const routeTables = await discovery.findRouteTables(vpcId);
+
+// Encryption
+const kmsKey = await discovery.findDefaultKMSKey();
+
+// Account Information
+const accountId = await discovery.getAccountId();
+```
+
+**Resource Discovery Triggers** (`serverless-template.js:10-17`):
+```javascript
+const shouldRunDiscovery = (AppDefinition) => {
+    return (
+        AppDefinition.vpc?.enable === true ||                                    // VPC deployment
+        AppDefinition.encryption?.useDefaultKMSForFieldLevelEncryption === true || // KMS encryption
+        AppDefinition.ssm?.enable === true                                       // SSM parameters
+    );
+};
+```
+
+### IAM Policy Generator (`iam-generator.js:12-885`)
+
+**Purpose**: Generate least-privilege IAM policies based on app definition features
+
+**Policy Generation Modes**:
+- **Auto Mode**: Detects features from app definition and generates appropriate policies
+- **Basic Mode**: Minimal permissions for simple deployments  
+- **Full Mode**: Complete permissions for all features
+
+**Feature-Based Policy Generation**:
+```javascript
+const features = {
+    vpc: appDefinition.vpc?.enable === true,                    // EC2 VPC permissions
+    kms: appDefinition.encryption?.useDefaultKMSForFieldLevelEncryption === true, // KMS permissions  
+    ssm: appDefinition.ssm?.enable === true,                   // SSM Parameter Store permissions
+    websockets: appDefinition.websockets?.enable === true      // API Gateway WebSocket permissions
+};
+```
+
+**Generated IAM Resources**:
+- **Deployment User**: IAM user for CI/CD deployments
+- **Lambda Execution Roles**: Roles for Lambda function execution
+- **CloudFormation Roles**: Roles for infrastructure stack management
+- **Service-Specific Policies**: Tailored policies for each AWS service used
+
+### Build-Time Discovery (`build-time-discovery.js:1-300`)
+
+**Purpose**: Integration between AWS discovery and serverless deployment process
+
+**Integration Points**:
+- **Pre-Build Hook**: Runs discovery before serverless deployment
+- **Environment Injection**: Sets discovered resources as environment variables
+- **Template Variables**: Replaces placeholders in serverless templates
+- **Error Handling**: Graceful fallbacks when discovery fails
+
+**Environment Variable Injection**:
+```bash
+# Automatically set by build-time discovery
+AWS_DISCOVERY_VPC_ID=vpc-12345678
+AWS_DISCOVERY_SECURITY_GROUP_ID=sg-12345678  
+AWS_DISCOVERY_SUBNET_ID_1=subnet-12345678
+AWS_DISCOVERY_SUBNET_ID_2=subnet-87654321
+AWS_DISCOVERY_ROUTE_TABLE_ID=rtb-12345678
+AWS_DISCOVERY_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
+```
+
+## Phase 3 Infrastructure Components
+
+### Enhanced Monitoring (`cloudformation/monitoring-infrastructure.yaml`)
+
+**Advanced CloudWatch Configuration**:
+- **Custom Dashboards**: Multi-service monitoring dashboards
+- **Composite Alarms**: System health monitoring with multiple metrics
+- **Code Generation Monitoring**: AI/ML service performance tracking
+- **UI Distribution Monitoring**: CDN and S3 performance metrics
+- **Cross-Stack Dependencies**: Monitoring across infrastructure stacks
+
+### CDN Infrastructure (`cloudformation/cdn-infrastructure.yaml`)
+
+**CloudFront Distribution System**:
+- **S3 Origin**: Multi-framework UI package storage
+- **Custom Domains**: Route 53 integration for branded URLs
+- **Lambda@Edge**: Package deployment automation
+- **API Gateway Integration**: RESTful package management API
+- **Cache Optimization**: Intelligent caching for UI assets
+
+### Code Generation Infrastructure (`cloudformation/codegen-infrastructure.yaml`)
+
+**AI/ML-Powered Code Generation Platform**:
+- **SQS Queue System**: Asynchronous generation request processing
+- **Lambda Functions**: AI/ML integration for code generation
+- **DynamoDB Tracking**: Generation request and status tracking
+- **S3 Template Storage**: Version-controlled template repository
+- **ElastiCache**: Template and generated code caching
+
+### Advanced Alerting (`cloudformation/alerting-infrastructure.yaml`)
+
+**Multi-Channel Alerting System**:
+- **SNS Topics**: Severity-based alert routing (critical, warning, info)
+- **Lambda Processing**: Alert enrichment and routing logic
+- **PagerDuty Integration**: On-call escalation for critical issues
+- **Slack Integration**: Team collaboration and alert management
+- **Composite Health Checks**: System-wide health monitoring
+
+### CI/CD Pipeline (`cloudformation/deployment-pipeline.yaml`)
+
+**Automated Deployment Pipeline**:
+- **CodePipeline**: Multi-stage deployment workflow
+- **CodeBuild Projects**: Separate build processes for backend and UI
+- **GitHub Integration**: Source code management and webhooks
+- **Multi-Environment**: Development, staging, production environments
+- **Approval Gates**: Manual approval for production deployments
+
+## Infrastructure Configuration Patterns
+
+### VPC-Enabled Deployment
+```javascript
+const vpcConfig = {
+    vpc: {
+        enable: true,
+        createNew: false,          // Use existing default VPC
+        enableVPCEndpoints: true   // Create endpoints for AWS services
+    }
+};
+
+// Results in Lambda functions deployed in private subnets
+// with VPC endpoints for S3, DynamoDB, SQS, SNS, etc.
+```
+
+### KMS Encryption Setup
+```javascript
+const encryptionConfig = {
+    encryption: {
+        useDefaultKMSForFieldLevelEncryption: true
+    }
+};
+
+// Automatically discovers customer-managed KMS key
+// Sets up Lambda environment variables for encryption
+// Configures IAM permissions for KMS operations
+```
+
+### SSM Parameter Store Integration
+```javascript
+const ssmConfig = {
+    ssm: {
+        enable: true
+    }
+};
+
+// Creates SSM parameters for configuration management
+// Sets up IAM permissions for parameter access
+// Enables secure configuration without hardcoding
+```
+
+### WebSocket Configuration (Phase 3)
+```javascript
+const websocketConfig = {
+    websockets: {
+        enable: true
+    }
+};
+
+// Creates API Gateway WebSocket API
+// Sets up connection management Lambda functions
+// Configures route handlers for WebSocket messages
+```
+
+## Security Architecture
+
+### IAM Permission Structure
+
+**Lambda Execution Permissions**:
+- **VPC Access**: ENI creation/deletion for VPC deployment
+- **Encryption**: KMS key usage for field-level encryption
+- **Storage**: S3 bucket operations for file handling
+- **Queues**: SQS send/receive for background job processing
+- **Parameters**: SSM parameter read access for configuration
+- **Logging**: CloudWatch Logs creation and writing
+
+**Deployment Permissions**:
+- **CloudFormation**: Stack create/update/delete operations
+- **IAM**: Role and policy management (limited scope)
+- **Lambda**: Function management and configuration
+- **API Gateway**: API creation and configuration
+- **Resource Discovery**: Read-only access for resource discovery
+
+### Network Security Model
+
+**Private Subnet Deployment**:
+```javascript
+// Lambda functions deployed in private subnets
+// No direct internet access - uses NAT Gateway or VPC endpoints
+{
+    vpc: { enable: true },
+    // Automatically configures:
+    // - Private subnet placement
+    // - Security group associations  
+    // - VPC endpoints for AWS services
+}
+```
+
+**VPC Endpoint Strategy**:
+- **S3 Gateway Endpoint**: Cost-effective S3 access
+- **Interface Endpoints**: SQS, SNS, DynamoDB, KMS, SSM
+- **DNS Resolution**: Private DNS for AWS services
+- **Security Groups**: Restricted access to required ports/protocols
+
+### Encryption Implementation
+
+**Field-Level Encryption**:
+```javascript
+// Automatic KMS integration
+{
+    encryption: { useDefaultKMSForFieldLevelEncryption: true },
+    // Results in:
+    // - KMS key discovery and configuration
+    // - Lambda environment variables for encryption
+    // - IAM permissions for KMS operations
+    // - Automatic encrypt/decrypt in data layer
+}
+```
+
+**Data at Rest**:
+- **S3 Buckets**: SSE-S3 or SSE-KMS encryption
+- **DynamoDB**: Encryption at rest with KMS
+- **SQS Queues**: Server-side encryption
+- **Lambda Environment**: Encrypted environment variables
+
+## Deployment Automation
+
+### Infrastructure Deployment Process
+
+**Discovery and Template Generation**:
+```bash
+# 1. AWS resource discovery
+node aws-discovery.js --region us-east-1
+
+# 2. Serverless template generation  
+node serverless-template.js --app-definition ./app-definition.js
+
+# 3. IAM policy generation
+node iam-generator.js --mode auto --app-definition ./app-definition.js
+
+# 4. CloudFormation deployment
+serverless deploy --stage production
+```
+
+**Environment Variable Management**:
+```javascript
+// Reserved AWS variables automatically skipped
+const reservedVars = [
+    '_HANDLER', '_X_AMZN_TRACE_ID', 'AWS_DEFAULT_REGION',
+    'AWS_EXECUTION_ENV', 'AWS_REGION', 'AWS_LAMBDA_FUNCTION_NAME',
+    'AWS_LAMBDA_FUNCTION_MEMORY_SIZE', 'AWS_LAMBDA_FUNCTION_VERSION',
+    'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN'
+];
+
+// User variables converted to serverless references
+{ MY_VAR: true } → { MY_VAR: "${env:MY_VAR, ''}" }
+```
+
+### Testing Strategy
+
+**Infrastructure Validation Tests** (`integration.test.js:1-450`):
+- **Template Generation**: Validate generated serverless.yml syntax
+- **Resource Discovery**: Test AWS API integration with mock data
+- **IAM Policy**: Validate policy syntax and permissions
+- **Cross-Stack Dependencies**: Test Phase 3 stack interactions
+- **CloudFormation Limits**: Validate template size and resource counts
+
+**Mock Data Patterns**:
+```javascript
+const mockAWSResources = {
+    defaultVpcId: 'vpc-12345678',
+    defaultSecurityGroupId: 'sg-12345678', 
+    privateSubnetId1: 'subnet-private-1',
+    privateSubnetId2: 'subnet-private-2',
+    defaultKmsKeyId: 'arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012',
+    routeTableId: 'rtb-12345678'
+};
+```
+
+## Performance Optimization
+
+### Lambda Cold Start Optimization
+- **Provisioned Concurrency**: Configure for critical functions
+- **VPC Optimization**: Use VPC endpoints to reduce ENI creation time
+- **Layer Strategy**: Share common dependencies via Lambda layers
+- **Function Sizing**: Right-size memory allocation for performance/cost
+
+### Cost Optimization Strategies
+- **VPC Endpoints**: Reduce NAT Gateway data transfer costs
+- **S3 Intelligent Tiering**: Automatic storage class optimization  
+- **CloudWatch Log Retention**: Configure appropriate retention periods
+- **Reserved Capacity**: Use reserved concurrency for predictable workloads
+
+### Infrastructure Scaling
+- **Auto Scaling**: Configure Lambda concurrency limits
+- **DynamoDB**: On-demand billing for variable workloads
+- **SQS**: Use appropriate queue types (standard vs FIFO)
+- **CloudFront**: Global edge locations for UI distribution
+
+## Anti-Patterns to Avoid
+
+❌ **Don't hardcode AWS resource IDs** - use discovery system for dynamic configuration  
+❌ **Don't bypass VPC security** - always deploy Lambda functions in private subnets when VPC enabled  
+❌ **Don't create infrastructure manually** - use CloudFormation templates for consistency  
+❌ **Don't ignore IAM least privilege** - use generated policies based on actual feature usage  
+❌ **Don't skip resource discovery** - discovery ensures compatibility with existing infrastructure  
+❌ **Don't expose secrets in templates** - use SSM Parameter Store or Secrets Manager  
+❌ **Don't ignore CloudFormation limits** - validate template size and resource counts
+
+## Troubleshooting Common Issues
+
+### AWS Discovery Failures
+```bash
+# Check AWS credentials and region
+aws sts get-caller-identity
+echo $AWS_REGION
+
+# Test specific discovery functions
+node -e "
+  const { AWSDiscovery } = require('./aws-discovery');
+  const discovery = new AWSDiscovery('us-east-1');
+  discovery.findDefaultVpc().then(console.log).catch(console.error);
+"
+```
+
+### Serverless Deployment Issues
+```bash
+# Enable debug logging for serverless
+SLS_DEBUG=true serverless deploy
+
+# Validate generated template
+serverless print > template.yml
+
+# Check CloudFormation template syntax
+aws cloudformation validate-template --template-body file://template.yml
+```
+
+### VPC Configuration Problems
+- **ENI Limits**: Check elastic network interface limits in target subnets
+- **Security Groups**: Ensure security groups allow required traffic
+- **Route Tables**: Verify routing for VPC endpoints and NAT Gateway
+- **DNS Resolution**: Check VPC DNS settings for private DNS names
+
+### KMS Encryption Issues
+- **Key Permissions**: Ensure IAM roles have KMS usage permissions
+- **Key Policy**: Check KMS key policy allows Lambda function usage
+- **Region Consistency**: Ensure KMS key is in same region as Lambda
+- **Alias Usage**: Use key ARN rather than alias for reliability
+
+## Environment Variables Reference
+
+### AWS Discovery Variables
+```bash
+# Set by discovery process
+AWS_DISCOVERY_VPC_ID=vpc-12345678
+AWS_DISCOVERY_SECURITY_GROUP_ID=sg-12345678
+AWS_DISCOVERY_SUBNET_ID_1=subnet-12345678
+AWS_DISCOVERY_SUBNET_ID_2=subnet-87654321
+AWS_DISCOVERY_ROUTE_TABLE_ID=rtb-12345678
+AWS_DISCOVERY_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
+```
+
+### Serverless Framework Variables
+```bash
+# Set by serverless during deployment
+AWS_REGION=us-east-1
+STAGE=production
+SERVICE_NAME=my-frigg-app
+```
+
+### Development/Testing Variables
+```bash
+# Skip discovery in test environments
+SKIP_AWS_DISCOVERY=true
+
+# Use mock data for testing
+USE_MOCK_AWS_DATA=true
+```
+
+## Related Documentation
+
+- **Phase 3 Deployment**: See `DEPLOYMENT-INSTRUCTIONS.md` for Phase 3 features
+- **AWS Discovery**: See `AWS-DISCOVERY-TROUBLESHOOTING.md` for troubleshooting
+- **IAM Policies**: See `IAM-POLICY-TEMPLATES.md` for policy examples
+- **Testing Strategy**: See `README-TESTING.md` for testing approach
+- **WebSocket Config**: See `WEBSOCKET-CONFIGURATION.md` for WebSocket setup

package/infrastructure/IAM-POLICY-TEMPLATES.md

@@ -83,27 +83,45 @@ aws cloudformation update-stack \
 For custom policy generation based on your app definition:
 
 ```javascript
-const { generateIAMPolicy, generateIAMCloudFormation } = require('./iam-generator');
+const { generateIAMPolicy, generateIAMCloudFormation, getFeatureSummary } = require('./iam-generator');
 
 // Generate basic JSON policy
 const basicPolicy = generateIAMPolicy('basic');
 
-// Generate full JSON policy  
+// Generate full JSON policy
 const fullPolicy = generateIAMPolicy('full');
 
-// Generate CloudFormation template with auto-detection
-const autoTemplate = generateIAMCloudFormation(appDefinition, { mode: 'auto' });
-
-// Generate CloudFormation template with specific mode
-const basicTemplate = generateIAMCloudFormation(appDefinition, { mode: 'basic' });
-const fullTemplate = generateIAMCloudFormation(appDefinition, { mode: 'full' });
+// Generate CloudFormation template with auto-detected features
+const summary = getFeatureSummary(appDefinition);
+const template = generateIAMCloudFormation({
+    appName: summary.appName,
+    features: summary.features,
+    userPrefix: 'frigg-deployment-user',
+    stackName: 'frigg-deployment-iam'
+});
+
+// Or manually specify features
+const customTemplate = generateIAMCloudFormation({
+    appName: 'my-app',
+    features: {
+        vpc: true,
+        kms: true,
+        ssm: true,
+        websockets: false
+    },
+    userPrefix: 'my-deployment-user',
+    stackName: 'my-deployment-stack'
+});
 ```
 
-### Generator Modes
+### Feature Detection
+
+Use `getFeatureSummary(appDefinition)` to automatically detect features from your app definition:
 
-- **`basic`** - Core permissions only, ignores app definition features
-- **`full`** - All features enabled, ignores app definition features  
-- **`auto`** - Analyzes app definition and enables features as needed (default)
+```javascript
+const summary = getFeatureSummary(appDefinition);
+// Returns: { appName, features: { core, vpc, kms, ssm, websockets }, integrationCount }
+```
 
 ## Security Best Practices
 

package/infrastructure/create-frigg-infrastructure.js

@@ -1,7 +1,6 @@
 const path = require('path');
 const fs = require('fs-extra');
 const { composeServerlessDefinition } = require('./serverless-template');
-
 const { findNearestBackendPackageJson } = require('@friggframework/core');
 
 async function createFriggInfrastructure() {
@@ -25,7 +24,6 @@ async function createFriggInfrastructure() {
     // ));
     const definition = await composeServerlessDefinition(
         appDefinition,
-        backend.IntegrationFactory
     );
 
     return {

package/infrastructure/iam-generator.js

@@ -1,52 +1,31 @@
 const path = require('path');
 
 /**
- * Generate IAM CloudFormation template based on AppDefinition
- * @param {Object} appDefinition - Application definition object
+ * Generate IAM CloudFormation template
  * @param {Object} options - Generation options
- * @param {string} [options.deploymentUserName='frigg-deployment-user'] - IAM user name
+ * @param {string} [options.appName='Frigg'] - Application name
+ * @param {Object} [options.features={}] - Enabled features { vpc, kms, ssm, websockets }
+ * @param {string} [options.userPrefix='frigg-deployment-user'] - IAM user name prefix
  * @param {string} [options.stackName='frigg-deployment-iam'] - CloudFormation stack name
- * @param {string} [options.mode='auto'] - Policy mode: 'basic', 'full', or 'auto' (auto-detect from appDefinition)
  * @returns {string} CloudFormation YAML template
  */
-function generateIAMCloudFormation(appDefinition, options = {}) {
-    const { deploymentUserName = 'frigg-deployment-user', mode = 'auto' } =
-        options;
-
-    // Determine which features are enabled based on mode
-    let features;
-    if (mode === 'basic') {
-        features = {
-            vpc: false,
-            kms: false,
-            ssm: false,
-            websockets: appDefinition.websockets?.enable === true,
-        };
-    } else if (mode === 'full') {
-        features = {
-            vpc: true,
-            kms: true,
-            ssm: true,
-            websockets: appDefinition.websockets?.enable === true,
-        };
-    } else {
-        // mode === 'auto'
-        features = {
-            vpc: appDefinition.vpc?.enable === true,
-            kms:
-                appDefinition.encryption
-                    ?.fieldLevelEncryptionMethod === 'kms',
-            ssm: appDefinition.ssm?.enable === true,
-            websockets: appDefinition.websockets?.enable === true,
-        };
-    }
+function generateIAMCloudFormation(options = {}) {
+    const {
+        appName = 'Frigg',
+        features = {},
+        userPrefix = 'frigg-deployment-user',
+        stackName = 'frigg-deployment-iam'
+    } = options;
+
+    const deploymentUserName = userPrefix;
+
+    // Features are already analyzed by caller (use getFeatureSummary to extract features from appDefinition)
+    // Expected features: { vpc, kms, ssm, websockets }
 
     // Build the CloudFormation template
     const template = {
         AWSTemplateFormatVersion: '2010-09-09',
-        Description: `IAM roles and policies for ${
-            appDefinition.name || 'Frigg'
-        } application deployment pipeline`,
+        Description: `IAM roles and policies for ${appName} application deployment pipeline`,
 
         Parameters: {
             DeploymentUserName: {
@@ -829,6 +808,7 @@ function generateIAMPolicy(mode = 'basic') {
 
 module.exports = {
     generateIAMCloudFormation,
+    generateCloudFormationTemplate: generateIAMCloudFormation, // Alias for generate-command/index.js compatibility
     getFeatureSummary,
     generateBasicIAMPolicy,
     generateFullIAMPolicy,