@friggframework/devtools 2.0.0--canary.428.2abc64a.0 → 2.0.0--canary.395.eb0264e.0

package/infrastructure/README.md

@@ -61,7 +61,8 @@ infrastructure/
 
 Generates complete serverless.yml configurations with:
 
--   VPC configuration and resource discovery
+-   VPC configuration and resource discovery (with optional self-healing)
+-   NAT/EIP management strategies (`discover`, `createAndManage`, `useExisting`)
 -   KMS encryption for field-level encryption
 -   SSM Parameter Store integration
 -   Integration-specific functions and queues
@@ -69,12 +70,13 @@ Generates complete serverless.yml configurations with:
 
 #### 2. AWS Discovery (`aws-discovery.js`)
 
-Automatically discovers existing AWS resources:
+Automatically discovers existing AWS resources and highlights misconfigurations:
 
 -   Default VPC and security groups
--   Private subnets for Lambda functions
+-   Private subnets for Lambda functions (with routing validation)
 -   Customer-managed KMS keys
 -   Route tables for VPC endpoints
+-   NAT gateways / Elastic IPs and whether remediation is required
 
 #### 3. Build-Time Discovery (`build-time-discovery.js`)
 
@@ -147,10 +149,18 @@ const appDefinition = {
   // VPC configuration
   vpc: {
     enable: true,
-    createNew: false,           // Use existing VPC (default)
-    securityGroupIds: [...],    // Optional: custom security groups
-    subnetIds: [...],          // Optional: custom subnets
-    enableVPCEndpoints: true   // Optional: create VPC endpoints
+    management: 'discover',     // 'discover' | 'create-new' | 'use-existing'
+    selfHeal: true,             // Let the template repair routing/NAT issues
+    securityGroupIds: [...],    // Optional: custom security groups or CFN Refs
+    subnets: {
+      management: 'discover',   // 'discover' | 'create' | 'use-existing'
+      ids: [...],               // Required when management is 'use-existing'
+    },
+    natGateway: {
+      management: 'discover',   // 'discover' | 'createAndManage' | 'useExisting'
+      id: 'nat-xxxxxxxx',       // Required when management is 'useExisting'
+    },
+    enableVPCEndpoints: true    // Optional: create VPC endpoints
   },
 
   // KMS encryption
@@ -164,7 +174,7 @@ const appDefinition = {
     enable: true
   },
 
-  // WebSocket support (Phase 3)
+  // WebSocket support (optional)
   websockets: {
     enable: true
   },
@@ -187,6 +197,7 @@ 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_PUBLIC_SUBNET_ID=subnet-abcdef12
 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
 

package/infrastructure/aws-discovery.test.js

@@ -1036,11 +1036,49 @@ describe('AWSDiscovery', () => {
             const result = await discovery.discoverResources({ selfHeal: true });
 
             expect(result).toMatchObject({
+                defaultVpcId: 'vpc-12345678',
+                privateSubnetId1: 'subnet-1',
+                privateSubnetId2: 'subnet-2',
+                publicSubnetId: 'subnet-public-1',
                 subnetConversionRequired: true,
                 privateSubnetsWithWrongRoutes: ['subnet-1']
             });
         });
 
+        it('should surface subnet analysis summary for diagnostic tooling', async () => {
+            const mockVpc = { VpcId: 'vpc-987654321', CidrBlock: '10.0.0.0/16' };
+            const mockSubnets = [
+                { SubnetId: 'subnet-public-a', AvailabilityZone: 'us-east-1a' },
+                { SubnetId: 'subnet-private-b', AvailabilityZone: 'us-east-1b' }
+            ];
+            const mockSecurityGroup = { GroupId: 'sg-22222222' };
+            const mockRouteTable = { RouteTableId: 'rtb-22222222' };
+
+            jest.spyOn(discovery, 'findDefaultVpc').mockResolvedValue(mockVpc);
+            jest.spyOn(discovery, 'findPrivateSubnets').mockResolvedValue(mockSubnets);
+            jest.spyOn(discovery, 'findPublicSubnets').mockResolvedValue({ SubnetId: 'subnet-nat-home' });
+            jest.spyOn(discovery, 'findDefaultSecurityGroup').mockResolvedValue(mockSecurityGroup);
+            jest.spyOn(discovery, 'findPrivateRouteTable').mockResolvedValue(mockRouteTable);
+            jest.spyOn(discovery, 'findDefaultKmsKey').mockResolvedValue(null);
+            jest.spyOn(discovery, 'findExistingNatGateway').mockResolvedValue({
+                NatGatewayId: 'nat-2222',
+                NatGatewayAddresses: [{ AllocationId: 'eipalloc-2222' }],
+                _isInPrivateSubnet: false
+            });
+            jest.spyOn(discovery, 'isSubnetPrivate')
+                .mockImplementation((subnetId) => subnetId === 'subnet-private-b');
+
+            const result = await discovery.discoverResources({ selfHeal: true });
+
+            expect(result.defaultVpcId).toBe('vpc-987654321');
+            expect(result.subnetConversionRequired).toBe(true);
+            expect(result.privateSubnetsWithWrongRoutes).toEqual(['subnet-public-a']);
+            expect(result.privateSubnetId1).toBe('subnet-public-a');
+            expect(result.privateSubnetId2).toBe('subnet-private-b');
+            expect(result.existingNatGatewayId).toBe('nat-2222');
+            expect(result.existingElasticIpAllocationId).toBe('eipalloc-2222');
+        });
+
         it('should handle selfHeal option', async () => {
             const mockVpc = { VpcId: 'vpc-12345678' };
             const mockSubnets = [

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/serverless-template.js

@@ -2,10 +2,19 @@ const path = require('path');
 const fs = require('fs');
 const { AWSDiscovery } = require('./aws-discovery');
 
-const shouldRunDiscovery = (AppDefinition) =>
-    AppDefinition.vpc?.enable === true ||
-    AppDefinition.encryption?.fieldLevelEncryptionMethod === 'kms' ||
-    AppDefinition.ssm?.enable === true;
+const shouldRunDiscovery = (AppDefinition) => {
+    // Check if we're running in offline mode (local development)
+    // Set IS_OFFLINE=true in your .env file for local development
+    if (process.env.IS_OFFLINE === 'true') {
+        console.log('⏭️  Skipping AWS discovery for local development (IS_OFFLINE=true)');
+        return false;
+    }
+
+    // Only run discovery if VPC, KMS encryption, or SSM is enabled
+    return AppDefinition.vpc?.enable === true ||
+           AppDefinition.encryption?.fieldLevelEncryptionMethod === 'kms' ||
+           AppDefinition.ssm?.enable === true;
+};
 
 const getAppEnvironmentVars = (AppDefinition) => {
     const envVars = {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friggframework/devtools",
   "prettier": "@friggframework/prettier-config",
-  "version": "2.0.0--canary.428.2abc64a.0",
+  "version": "2.0.0--canary.395.eb0264e.0",
   "dependencies": {
     "@aws-sdk/client-ec2": "^3.835.0",
     "@aws-sdk/client-kms": "^3.835.0",
@@ -9,8 +9,8 @@
     "@babel/eslint-parser": "^7.18.9",
     "@babel/parser": "^7.25.3",
     "@babel/traverse": "^7.25.3",
-    "@friggframework/schemas": "2.0.0--canary.428.2abc64a.0",
-    "@friggframework/test": "2.0.0--canary.428.2abc64a.0",
+    "@friggframework/schemas": "2.0.0--canary.395.eb0264e.0",
+    "@friggframework/test": "2.0.0--canary.395.eb0264e.0",
     "@hapi/boom": "^10.0.1",
     "@inquirer/prompts": "^5.3.8",
     "axios": "^1.7.2",
@@ -32,8 +32,8 @@
     "serverless-http": "^2.7.0"
   },
   "devDependencies": {
-    "@friggframework/eslint-config": "2.0.0--canary.428.2abc64a.0",
-    "@friggframework/prettier-config": "2.0.0--canary.428.2abc64a.0",
+    "@friggframework/eslint-config": "2.0.0--canary.395.eb0264e.0",
+    "@friggframework/prettier-config": "2.0.0--canary.395.eb0264e.0",
     "aws-sdk-client-mock": "^4.1.0",
     "aws-sdk-client-mock-jest": "^4.1.0",
     "jest": "^30.1.3",
@@ -68,5 +68,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "2abc64a478259d105bc7a1ddd08e39740b4541a0"
+  "gitHead": "eb0264e7fb4d26ee5fa81fb693905775609e5671"
 }

package/test/index.js

@@ -1,11 +1,9 @@
-const {testDefinitionRequiredAuthMethods} = require('./auther-definition-method-tester');
-const {createMockIntegration, createMockApiObject} = require('./mock-integration');
-const { testAutherDefinition } = require('./auther-definition-tester');
+const { testDefinitionRequiredAuthMethods } = require('./auther-definition-method-tester');
+const { createMockIntegration, createMockApiObject } = require('./mock-integration');
 
 
 module.exports = {
     createMockIntegration,
     createMockApiObject,
     testDefinitionRequiredAuthMethods,
-    testAutherDefinition,
 };

package/test/mock-integration.js

@@ -1,8 +1,4 @@
 const {
-    Auther,
-    Credential,
-    Entity,
-    IntegrationFactory,
     createObjectId,
 } = require('@friggframework/core');
 
@@ -11,7 +7,6 @@ async function createMockIntegration(
     userId = null,
     config = { type: IntegrationClass.Definition.name }
 ) {
-    const integrationFactory = new IntegrationFactory([IntegrationClass]);
     userId = userId || createObjectId();
 
     const insertOptions = {
@@ -24,10 +19,8 @@ async function createMockIntegration(
     const entities = [];
     for (const moduleName in IntegrationClass.modules) {
         const ModuleDef = IntegrationClass.Definition.modules[moduleName];
-        const module = await Auther.getInstance({
-            definition: ModuleDef,
-            userId: userId,
-        });
+        // todo: create module using the new architecture
+        const module = {}
         const credential = await module.CredentialModel.findOneAndUpdate(
             user,
             { $set: user },
@@ -51,11 +44,8 @@ async function createMockIntegration(
         );
     }
 
-    const integration = await integrationFactory.createIntegration(
-        entities,
-        userId,
-        config
-    );
+    // todo: create integration using the new architecture
+    const integration = {}
 
     integration.id = integration.record._id;
 

package/infrastructure/AWS-DISCOVERY-TROUBLESHOOTING.md

@@ -1,245 +0,0 @@
-# AWS Discovery Troubleshooting Guide
-
-## Overview
-
-AWS Discovery automatically finds your default AWS resources (VPC, subnets, security groups, KMS keys) during the build process. This eliminates the need to manually specify resource IDs in your configuration.
-
-## When AWS Discovery Runs
-
-AWS Discovery runs automatically during `frigg build` and `frigg deploy` when your AppDefinition includes:
-
-- `vpc.enable: true` - VPC support
-- `encryption.fieldLevelEncryptionMethod: 'kms'` - KMS encryption
-- `ssm.enable: true` - SSM Parameter Store
-
-## Fail-Fast Behavior
-
-⚠️ **Important:** If you enable these features, discovery **must succeed**. The build will fail if:
-- AWS credentials are missing or invalid
-- Required AWS permissions are not granted
-- No VPC/subnets exist in your region
-- Discovery times out or encounters errors
-
-This prevents deployments with incorrect or missing AWS resources, which could cause security issues or deployment failures.
-
-## Common Issues
-
-### 1. "Variables resolution errored" - Environment Variables Not Found
-
-**Error:**
-```
-Cannot resolve variable at "provider.vpc.securityGroupIds.0": Value not found at "env" source
-Cannot resolve variable at "provider.vpc.subnetIds.0": Value not found at "env" source
-```
-
-**Cause:** AWS discovery didn't run or failed to set environment variables.
-
-**Solutions:**
-
-#### Option A: Run Discovery Manually
-```bash
-# Run discovery before building
-node node_modules/@friggframework/devtools/infrastructure/run-discovery.js
-
-# Then build
-npx frigg build
-```
-
-#### Option B: Check Prerequisites
-1. **AWS Credentials:** Ensure AWS CLI is configured
-   ```bash
-   aws configure list
-   aws sts get-caller-identity
-   ```
-
-2. **IAM Permissions:** User needs discovery permissions (see [AWS-IAM-CREDENTIAL-NEEDS.md](./AWS-IAM-CREDENTIAL-NEEDS.md))
-   - `sts:GetCallerIdentity`
-   - `ec2:DescribeVpcs`
-   - `ec2:DescribeSubnets`
-   - `ec2:DescribeSecurityGroups`
-   - `ec2:DescribeRouteTables`
-   - `kms:ListKeys`
-   - `kms:DescribeKey`
-
-3. **Default VPC:** Ensure you have a VPC in your AWS region
-   ```bash
-   aws ec2 describe-vpcs --region us-east-1
-   ```
-
-### 2. AWS SDK Not Installed
-
-**Error:**
-```bash
-🚨 AWS SDK not installed!
-Cannot find module '@aws-sdk/client-ec2'
-```
-
-**Cause:** AWS SDK dependencies are only installed when needed to keep bundle size minimal.
-
-**Solution:**
-```bash
-# Install required AWS SDK packages
-npm install @aws-sdk/client-ec2 @aws-sdk/client-kms @aws-sdk/client-sts
-
-# Then run discovery
-npx frigg build
-```
-
-**Note:** AWS SDK is optional - only install if you use VPC/KMS/SSM features.
-
-### 3. No Default VPC Found
-
-**Error:**
-```
-No VPC found in the account
-```
-
-**Cause:** Your AWS account doesn't have a default VPC or any VPCs in the current region.
-
-**Solutions:**
-
-#### Option A: Create Default VPC
-```bash
-aws ec2 create-default-vpc --region us-east-1
-```
-
-#### Option B: Disable VPC in AppDefinition
-```javascript
-// backend/index.js
-const appDefinition = {
-    // ... other config
-    vpc: {
-        enable: false  // Disable VPC support
-    }
-};
-```
-
-### 4. Permission Denied During Discovery
-
-**Error:**
-```
-User: arn:aws:iam::123456789012:user/my-user is not authorized to perform: ec2:DescribeVpcs
-```
-
-**Cause:** IAM user lacks discovery permissions.
-
-**Solution:**
-1. Update IAM policy with discovery permissions
-2. Or generate a custom IAM stack:
-   ```bash
-   npx frigg generate-iam
-   aws cloudformation deploy --template-file backend/infrastructure/frigg-deployment-iam.yaml --stack-name frigg-deployment-iam --capabilities CAPABILITY_NAMED_IAM
-   ```
-
-### 5. Region Configuration Issues
-
-**Error:**
-```
-No subnets found in VPC vpc-123456789
-```
-
-**Cause:** AWS discovery is looking in the wrong region or region has no subnets.
-
-**Solutions:**
-
-#### Option A: Set AWS Region
-```bash
-export AWS_REGION=us-east-1
-npx frigg build
-```
-
-#### Option B: Check Current Region
-```bash
-aws configure get region
-aws ec2 describe-availability-zones --query 'AvailabilityZones[0].RegionName'
-```
-
-## Manual Override
-
-If AWS discovery continues to fail, you can manually set environment variables:
-
-```bash
-# Find your actual resource IDs
-aws ec2 describe-vpcs --query 'Vpcs[0].VpcId' --output text
-aws ec2 describe-subnets --filters "Name=vpc-id,Values=vpc-12345678" --query 'Subnets[0:2].SubnetId' --output text
-
-# Set before building
-export AWS_DISCOVERY_VPC_ID=vpc-12345678
-export AWS_DISCOVERY_SECURITY_GROUP_ID=sg-12345678
-export AWS_DISCOVERY_SUBNET_ID_1=subnet-12345678
-export AWS_DISCOVERY_SUBNET_ID_2=subnet-87654321
-export AWS_DISCOVERY_PUBLIC_SUBNET_ID=subnet-abcdef12
-export AWS_DISCOVERY_ROUTE_TABLE_ID=rtb-12345678
-export AWS_DISCOVERY_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
-
-npx frigg build
-```
-
-**⚠️ Important:** Use real AWS resource IDs, not placeholder values. Fake IDs will cause deployment failures.
-
-## Debugging Discovery
-
-### Enable Verbose Logging
-```bash
-npx frigg build --verbose
-```
-
-### Test Discovery Standalone
-```bash
-# Test discovery without building
-node node_modules/@friggframework/devtools/infrastructure/run-discovery.js
-```
-
-### Check Environment Variables
-```bash
-# After running discovery
-printenv | grep AWS_DISCOVERY
-```
-
-## Recovery Steps
-
-If you're stuck, try this recovery process:
-
-1. **Verify AWS Setup**
-   ```bash
-   aws sts get-caller-identity
-   aws ec2 describe-vpcs --region us-east-1
-   ```
-
-2. **Check App Definition**
-   ```bash
-   # Ensure your backend/index.js exports Definition correctly
-   node -e "console.log(require('./backend/index.js').Definition)"
-   ```
-
-3. **Run Discovery Manually**
-   ```bash
-   node node_modules/@friggframework/devtools/infrastructure/run-discovery.js
-   ```
-
-4. **Disable Features Temporarily**
-   ```javascript
-   // backend/index.js - temporarily disable problematic features
-   const appDefinition = {
-       vpc: { enable: false },
-       encryption: { fieldLevelEncryptionMethod: 'aes' },
-       ssm: { enable: false }
-   };
-   ```
-
-5. **Build and Test**
-   ```bash
-   npx frigg build
-   ```
-
-## Getting Help
-
-If discovery continues to fail:
-
-1. **Check logs** for specific error messages
-2. **Verify IAM permissions** using the generated IAM stack
-3. **Test AWS CLI access** in your target region
-4. **Review AppDefinition** for correct feature flags
-5. **Try fallback values** as a temporary workaround
-
-The discovery system is designed to be resilient, but AWS environment differences can cause issues. Most problems are related to IAM permissions or missing AWS resources in the target region.