@friggframework/devtools 2.0.0-next.61 → 2.0.0-next.62

package/infrastructure/domains/health/docs/ACME-DEV-DRIFT-ANALYSIS.md

@@ -1,267 +0,0 @@
-# acme-integrations-dev Stack Drift Analysis
-
-**Date**: 2025-10-27
-**Stack**: acme-integrations-dev (us-east-1)
-**Status**: 65/100 Health Score (degraded)
-
-## Executive Summary
-
-The Lambda functions were **manually moved from Frigg VPC to Default VPC**, causing:
-- ✅ 16 orphaned resources (3 VPCs, 10 subnets, 3 security groups) - correctly detected
-- ⚠️ 32 property mismatch warnings (VPC drift on all 16 Lambda functions)
-
-**The template expects** Lambdas to use Frigg-managed VPC `vpc-0eadd96976d29ede7`.
-**But Lambdas actually use** AWS default VPC `vpc-01f21101d4ed6db59`.
-
-## Detailed Analysis
-
-### CloudFormation Template Expectations
-
-The template specifies Lambda functions should use:
-
-```yaml
-VpcConfig:
-  SecurityGroupIds:
-    - sg-07c01370e830b6ad6        # Frigg Lambda SG (in vpc-0eadd96976d29ede7)
-  SubnetIds:
-    - subnet-00ab9e0502e66aac3      # Private subnet 1 (in vpc-0eadd96976d29ede7)
-    - subnet-00d085a52937aaf91      # Private subnet 2 (in vpc-0eadd96976d29ede7)
-```
-
-**These resources belong to:** `vpc-0eadd96976d29ede7` (10.0.0.0/16)
-
-### Actual Lambda Configuration
-
-Lambda functions are actually running in:
-
-```json
-{
-  "VpcId": "vpc-01f21101d4ed6db59",    // AWS Default VPC (172.31.0.0/16)
-  "SecurityGroupIds": [
-    "sg-0aca40438d17344c4"             // Default VPC security group (NOT in template)
-  ],
-  "SubnetIds": [
-    "subnet-020d32e3ca398a041",        // Default VPC subnet 1 (NOT in template)
-    "subnet-0c186318804aba790"         // Default VPC subnet 2 (NOT in template)
-  ]
-}
-```
-
-**These resources belong to:** `vpc-01f21101d4ed6db59` (172.31.0.0/16) - AWS Default VPC
-
-### Orphaned Resources Analysis
-
-#### 1. VPC: vpc-0eadd96976d29ede7 (10.0.0.0/16) ✅ CORRECT VPC TO IMPORT
-
-**Status:**
-- Has CloudFormation tags: `stack-name=acme-integrations-dev`, `logical-id=FriggVPC`
-- NOT in CloudFormation stack (stack has 0 VPCs managed)
-- Contains subnets that are **EXPECTED by template**:
-  - `subnet-00ab9e0502e66aac3` (10.0.0.0/24) - Expected by template ✅
-  - `subnet-00d085a52937aaf91` (10.0.1.0/24) - Expected by template ✅
-- Contains security group that is **EXPECTED by template**:
-  - `sg-07c01370e830b6ad6` - Expected by template ✅
-
-**Conclusion:** This is the **CORRECT VPC** that should be imported! The template expects Lambdas to use this VPC, but they were manually moved to default VPC.
-
-**Stage Verification:** Has `STAGE=dev` tag ✅
-
-#### 2. VPC: vpc-0e2351eac99adcb83 (10.0.0.0/16) - OLD/DUPLICATE
-
-**Status:**
-- Has CloudFormation tags: `stack-name=acme-integrations-dev`, `logical-id=FriggVPC`
-- NOT in CloudFormation stack
-- Contains orphaned subnets NOT referenced by template
-- Same CIDR as vpc-0eadd96976d29ede7 (duplicate)
-
-**Conclusion:** Old/duplicate VPC, should be **DELETED**
-
-**Stage Verification:** Has `STAGE=dev` tag
-
-#### 3. VPC: vpc-020a0365610c05f0b (10.0.0.0/16) - OLD/DUPLICATE
-
-**Status:**
-- Has CloudFormation tags: `stack-name=acme-integrations-dev`, `logical-id=FriggVPC`
-- NOT in CloudFormation stack
-- Contains orphaned subnets NOT referenced by template
-- Same CIDR as vpc-0eadd96976d29ede7 (duplicate)
-
-**Conclusion:** Old/duplicate VPC, should be **DELETED**
-
-**Stage Verification:** Has `STAGE=dev` tag
-
-## What Happened?
-
-1. **Initial Deployment**: CloudFormation created `vpc-0eadd96976d29ede7` with subnets and security groups
-2. **VPC Removed from Stack**: VPC was removed from CloudFormation management (but resources still exist)
-3. **Manual Migration**: Lambda functions were manually updated to use default VPC instead
-4. **Result**: Template expects Frigg VPC, but Lambdas use default VPC → drift
-
-## Recommended Actions
-
-### Option 1: Import Frigg VPC and Let CloudFormation Fix Drift (RECOMMENDED)
-
-**Steps:**
-
-1. **Import the correct VPC and its resources:**
-   ```bash
-   # Import vpc-0eadd96976d29ede7 and its subnets/SG
-   frigg repair --import quo-integrations-dev
-   # When prompted, select ONLY vpc-0eadd96976d29ede7
-   ```
-
-2. **CloudFormation will automatically update Lambdas:**
-   - CloudFormation will detect the VPC/subnet/SG mismatch
-   - Next stack update will **automatically** update Lambda VPC configs
-   - Lambdas will be moved from default VPC back to Frigg VPC
-
-3. **Delete the duplicate VPCs:**
-   ```bash
-   aws ec2 delete-vpc --vpc-id vpc-0e2351eac99adcb83
-   aws ec2 delete-vpc --vpc-id vpc-020a0365610c05f0b
-   ```
-
-**CloudFormation Behavior:**
-- ✅ YES, CloudFormation WILL automatically update Lambda VPC configs
-- ✅ CloudFormation will handle the migration safely (blue-green deployment)
-- ✅ No downtime - new Lambda versions created, traffic switched over
-
-**Benefits:**
-- ✅ Stack returns to intended state (Lambdas in Frigg VPC)
-- ✅ Health score improves to 100/100
-- ✅ Proper VPC isolation restored
-- ✅ CloudFormation manages all resources again
-
-**Risks:**
-- ⚠️ Lambda cold starts during VPC migration (~10-30 seconds)
-- ⚠️ Must ensure Frigg VPC networking is configured correctly
-
-### Option 2: Update Template to Use Default VPC (NOT RECOMMENDED)
-
-**Steps:**
-
-1. Update serverless.yml to remove VPC configuration
-2. Deploy stack update
-3. Delete all 3 orphaned Frigg VPCs
-
-**Why NOT recommended:**
-- ❌ Loses VPC isolation benefits
-- ❌ Lambda functions exposed to internet (less secure)
-- ❌ Shared default VPC across all accounts
-- ❌ No control over networking
-
-### Option 3: Delete All and Let CloudFormation Recreate (RISKY)
-
-**Steps:**
-
-1. Delete all 3 orphaned VPCs
-2. Add VPC back to CloudFormation template
-3. Deploy stack update
-
-**Why RISKY:**
-- ❌ CloudFormation will create NEW VPC with different ID
-- ❌ Requires stack update to fix Lambda drift
-- ❌ More disruptive than import
-
-## Answering Your Questions
-
-### Q1: What are the drifted properties?
-
-**Answer:**
-- **Expected** (from template): Subnets in `vpc-0eadd96976d29ede7` (Frigg VPC)
-- **Actual** (in AWS): Subnets in `vpc-01f21101d4ed6db59` (default VPC)
-- **Cause**: Lambdas were manually moved to default VPC
-
-### Q2: Will CloudFormation migrate Lambdas if we import the VPC?
-
-**Answer:** ✅ **YES!**
-
-When you import `vpc-0eadd96976d29ede7` and its subnets/SG:
-1. CloudFormation will recognize the resources exist
-2. Next stack update will detect Lambda VPC config drift
-3. CloudFormation will automatically update Lambda functions to use imported VPC
-4. Migration happens safely with blue-green deployment (no downtime)
-
-### Q3: What's the right approach?
-
-**Answer:** **Import `vpc-0eadd96976d29ede7` and delete the other 2 VPCs**
-
-This VPC is the one the template expects, and it contains the correct subnets/SG that match the template.
-
-### Q4: Are these VPCs intended for -dev stage?
-
-**Answer:** ✅ **YES, all 3 VPCs have `STAGE=dev` tags**
-
-But only `vpc-0eadd96976d29ede7` contains the resources referenced by the template. The other 2 are duplicates/old deployments.
-
-## Implementation Plan
-
-1. ✅ **Verify VPC networking is correct:**
-   ```bash
-   # Check route tables, NAT gateways, internet gateways
-   aws ec2 describe-route-tables --filters "Name=vpc-id,Values=vpc-0eadd96976d29ede7"
-   aws ec2 describe-nat-gateways --filter "Name=vpc-id,Values=vpc-0eadd96976d29ede7"
-   ```
-
-2. ✅ **Import the correct VPC:**
-   ```bash
-   frigg repair --import quo-integrations-dev
-   # Select: vpc-0eadd96976d29ede7 ONLY
-   # Select: All subnets in vpc-0eadd96976d29ede7
-   # Select: sg-07c01370e830b6ad6
-   ```
-
-3. ✅ **Deploy stack update to fix Lambda drift:**
-   ```bash
-   frigg deploy --stage dev
-   # CloudFormation will update Lambda VPC configs automatically
-   ```
-
-4. ✅ **Verify Lambdas migrated successfully:**
-   ```bash
-   aws lambda get-function-configuration --function-name quo-integrations-dev-attio \
-     --query 'VpcConfig.{VpcId:VpcId,SubnetIds:SubnetIds}'
-   ```
-
-5. ✅ **Delete duplicate VPCs:**
-   ```bash
-   # Delete subnets first, then VPCs
-   aws ec2 delete-vpc --vpc-id vpc-0e2351eac99adcb83
-   aws ec2 delete-vpc --vpc-id vpc-020a0365610c05f0b
-   ```
-
-6. ✅ **Re-run health check:**
-   ```bash
-   frigg doctor quo-integrations-dev
-   # Should show 100/100 health score
-   ```
-
-## Next Steps for Relationship Analysis Implementation
-
-Based on this real-world scenario, the relationship analysis should:
-
-1. **Detect template-expected resources:**
-   - Parse CloudFormation template to find expected VPC config
-   - Extract subnet IDs, security group IDs from template
-
-2. **Match orphans against expected resources:**
-   - `vpc-0eadd96976d29ede7` contains expected subnets → **HIGH priority import**
-   - Other VPCs don't contain expected resources → **LOW priority (delete)**
-
-3. **Show recommendation:**
-   ```
-   ⚠ Multiple VPCs detected (3 orphaned)
-
-   Analysis:
-     1. vpc-0eadd96976d29ede7 - Contains resources expected by template [IMPORT THIS]
-        - subnet-00ab9e0502e66aac3 (expected)
-        - subnet-00d085a52937aaf91 (expected)
-        - sg-07c01370e830b6ad6 (expected)
-
-     2. vpc-0e2351eac99adcb83 - No expected resources [DELETE]
-     3. vpc-020a0365610c05f0b - No expected resources [DELETE]
-
-   Recommendation:
-     ✅ Import vpc-0eadd96976d29ede7 to restore template compliance
-     ❌ Delete vpc-0e2351eac99adcb83 and vpc-020a0365610c05f0b (old/unused)
-   ```

package/infrastructure/domains/health/docs/BUILD-VS-DEPLOYED-TEMPLATE-ANALYSIS.md

@@ -1,324 +0,0 @@
-# Build Template vs Deployed Template Analysis
-
-**CRITICAL DISCOVERY**: The local build template and deployed CloudFormation template are DIFFERENT!
-
-## The Discrepancy
-
-### Local Build Template (.serverless/cloudformation-template-update-stack.json)
-
-**Contains VPC Resources:**
-```json
-{
-  "Resources": {
-    "FriggVPC": { "Type": "AWS::EC2::VPC" },
-    "FriggPrivateSubnet1": { "Type": "AWS::EC2::Subnet" },
-    "FriggPrivateSubnet2": { "Type": "AWS::EC2::Subnet" },
-    "FriggPublicSubnet": { "Type": "AWS::EC2::Subnet" },
-    "FriggPublicSubnet2": { "Type": "AWS::EC2::Subnet" },
-    "FriggLambdaSecurityGroup": { "Type": "AWS::EC2::SecurityGroup" },
-    "FriggVPCEndpointSecurityGroup": { "Type": "AWS::EC2::SecurityGroup" }
-  }
-}
-```
-
-**Lambda VPC Config uses Refs:**
-```json
-{
-  "VpcConfig": {
-    "SecurityGroupIds": [{ "Ref": "FriggLambdaSecurityGroup" }],
-    "SubnetIds": [
-      { "Ref": "FriggPrivateSubnet1" },
-      { "Ref": "FriggPrivateSubnet2" }
-    ]
-  }
-}
-```
-
-### Deployed CloudFormation Template (in AWS)
-
-**Does NOT contain VPC Resources:**
-- ✅ Has Lambda functions
-- ✅ Has SQS queues
-- ✅ Has IAM roles
-- ❌ **NO VPC resources** (FriggVPC, FriggPrivateSubnet1, FriggPrivateSubnet2, etc.)
-
-**Lambda VPC Config uses Hardcoded Physical IDs:**
-```json
-{
-  "VpcConfig": {
-    "SecurityGroupIds": ["sg-07c01370e830b6ad6"],    // Hardcoded physical ID
-    "SubnetIds": [
-      "subnet-00ab9e0502e66aac3",                     // Hardcoded physical ID
-      "subnet-00d085a52937aaf91"                      // Hardcoded physical ID
-    ]
-  }
-}
-```
-
-## What This Means
-
-### 1. VPC Resources Were Removed from Stack
-
-At some point, the VPC resources were removed from CloudFormation management:
-- VPC was created by CloudFormation originally
-- VPC was later removed from the template/stack (but physical resources left in AWS)
-- Lambda functions still reference the VPC subnets/SG by physical ID
-
-### 2. Local Build != Deployed State
-
-**If you deploy the local build template now:**
-- CloudFormation will try to CREATE new VPC resources (FriggVPC, subnets, SG)
-- CloudFormation will FAIL because resources with those logical IDs already exist physically
-- OR it will create NEW resources with different physical IDs
-- Lambda functions will reference the NEW resources (via Ref)
-
-### 3. Import Operation is Complex
-
-When you import `vpc-0eadd96976d29ede7`:
-- You need to map it to the logical ID `FriggVPC` in the template
-- You need to import ALL related resources:
-  - `FriggPrivateSubnet1` → `subnet-00ab9e0502e66aac3`
-  - `FriggPrivateSubnet2` → `subnet-00d085a52937aaf91`
-  - `FriggLambdaSecurityGroup` → `sg-07c01370e830b6ad6`
-  - etc.
-
-## CloudFormation Import Process
-
-### How Import Works
-
-**Q: Will it know to grab the right VPC?**
-
-**A:** ❌ **NO, you must explicitly tell it which physical ID maps to which logical ID**
-
-CloudFormation import requires:
-```json
-{
-  "Resources": [
-    {
-      "ResourceType": "AWS::EC2::VPC",
-      "LogicalResourceId": "FriggVPC",
-      "ResourceIdentifier": {
-        "VpcId": "vpc-0eadd96976d29ede7"  // You specify this
-      }
-    },
-    {
-      "ResourceType": "AWS::EC2::Subnet",
-      "LogicalResourceId": "FriggPrivateSubnet1",
-      "ResourceIdentifier": {
-        "SubnetId": "subnet-00ab9e0502e66aac3"  // You specify this
-      }
-    },
-    // ... more resources
-  ]
-}
-```
-
-**Q: Will it clear or delete the old resources?**
-
-**A:** ❌ **NO, you must manually delete unused resources**
-
-CloudFormation import:
-- ✅ Adds existing resources to the stack (doesn't create or delete anything)
-- ✅ Updates Lambda Refs to point to imported resources
-- ❌ Does NOT delete the 2 unused VPCs
-- ❌ Does NOT clean up orphaned resources
-
-## The Right Approach
-
-### Step 1: Update Local Build Template to Match Deployed State
-
-**OPTION A: Remove VPC from local template (quick fix)**
-
-Remove VPC resources from `serverless.yml`:
-```yaml
-# Comment out or remove:
-# resources:
-#   Resources:
-#     FriggVPC: ...
-#     FriggPrivateSubnet1: ...
-```
-
-Then use hardcoded subnet/SG IDs:
-```yaml
-provider:
-  vpc:
-    securityGroupIds:
-      - sg-07c01370e830b6ad6
-    subnetIds:
-      - subnet-00ab9e0502e66aac3
-      - subnet-00d085a52937aaf91
-```
-
-**OPTION B: Import VPC resources to stack (proper fix)**
-
-1. Create import template with mappings
-2. Run CloudFormation import operation
-3. Redeploy with local template
-
-### Step 2: Decision Point
-
-**CRITICAL QUESTION: Do you want CloudFormation to manage the VPC?**
-
-**If YES (recommended for Frigg framework):**
-- ✅ Import `vpc-0eadd96976d29ede7` and its resources
-- ✅ CloudFormation will manage VPC lifecycle
-- ✅ Template and reality stay in sync
-- ✅ Proper infrastructure as code
-
-**If NO (simpler but less controlled):**
-- ✅ Remove VPC from local template
-- ✅ Use hardcoded subnet/SG IDs in serverless.yml
-- ✅ Manually manage VPC outside CloudFormation
-- ⚠️ Template drift will always exist
-
-## Recommended Action (CloudFormation Import)
-
-### Phase 1: Prepare Import Template
-
-```bash
-# 1. Get the local template
-cd /Users/sean/Documents/GitHub/quo--frigg/backend
-
-# 2. Create import-resources.json
-cat > import-resources.json <<EOF
-[
-  {
-    "ResourceType": "AWS::EC2::VPC",
-    "LogicalResourceId": "FriggVPC",
-    "ResourceIdentifier": { "VpcId": "vpc-0eadd96976d29ede7" }
-  },
-  {
-    "ResourceType": "AWS::EC2::Subnet",
-    "LogicalResourceId": "FriggPrivateSubnet1",
-    "ResourceIdentifier": { "SubnetId": "subnet-00ab9e0502e66aac3" }
-  },
-  {
-    "ResourceType": "AWS::EC2::Subnet",
-    "LogicalResourceId": "FriggPrivateSubnet2",
-    "ResourceIdentifier": { "SubnetId": "subnet-00d085a52937aaf91" }
-  },
-  {
-    "ResourceType": "AWS::EC2::SecurityGroup",
-    "LogicalResourceId": "FriggLambdaSecurityGroup",
-    "ResourceIdentifier": { "GroupId": "sg-07c01370e830b6ad6" }
-  }
-  // ... add other resources (public subnets, SGs, etc.)
-]
-EOF
-```
-
-### Phase 2: Create Change Set for Import
-
-```bash
-aws cloudformation create-change-set \
-  --stack-name quo-integrations-dev \
-  --change-set-name import-vpc-resources \
-  --change-set-type IMPORT \
-  --resources-to-import file://import-resources.json \
-  --template-body file://.serverless/cloudformation-template-update-stack.json \
-  --capabilities CAPABILITY_IAM \
-  --region us-east-1
-```
-
-### Phase 3: Review and Execute
-
-```bash
-# Review the change set
-aws cloudformation describe-change-set \
-  --stack-name quo-integrations-dev \
-  --change-set-name import-vpc-resources \
-  --region us-east-1
-
-# Execute if looks good
-aws cloudformation execute-change-set \
-  --stack-name quo-integrations-dev \
-  --change-set-name import-vpc-resources \
-  --region us-east-1
-```
-
-### Phase 4: Update Lambda VPC Configs
-
-After import, CloudFormation will:
-- ✅ Recognize VPC resources are in the stack
-- ✅ Lambda Refs will resolve to imported physical IDs
-- ✅ Next deploy will update Lambda VPC configs from default VPC back to Frigg VPC
-
-### Phase 5: Clean Up
-
-```bash
-# Delete unused VPCs
-aws ec2 delete-vpc --vpc-id vpc-0e2351eac99adcb83 --region us-east-1
-aws ec2 delete-vpc --vpc-id vpc-020a0365610c05f0b --region us-east-1
-```
-
-## Alternative: Simpler Approach (Remove VPC from Template)
-
-If you don't want CloudFormation to manage VPC:
-
-### Step 1: Update serverless.yml
-
-```yaml
-provider:
-  name: aws
-  vpc:
-    # Hardcode the VPC resources
-    securityGroupIds:
-      - sg-07c01370e830b6ad6
-    subnetIds:
-      - subnet-00ab9e0502e66aac3
-      - subnet-00d085a52937aaf91
-
-# Remove VPC resource definitions
-# resources:
-#   Resources:
-#     FriggVPC: ...
-```
-
-### Step 2: Deploy
-
-```bash
-serverless deploy --stage dev
-```
-
-### Step 3: Clean Up
-
-```bash
-# Delete all 3 orphaned VPCs
-aws ec2 delete-vpc --vpc-id vpc-0eadd96976d29ede7
-aws ec2 delete-vpc --vpc-id vpc-0e2351eac99adcb83
-aws ec2 delete-vpc --vpc-id vpc-020a0365610c05f0b
-```
-
-## Recommendation
-
-**For Frigg Framework consistency: Import VPC resources**
-
-Why:
-- ✅ Maintains infrastructure as code principles
-- ✅ VPC lifecycle managed by CloudFormation
-- ✅ Consistent with Frigg framework design
-- ✅ Template matches deployed state
-- ✅ `frigg doctor` will show 100/100 health
-
-**Trade-offs:**
-- ⚠️ More complex import process
-- ⚠️ Must map all VPC resources correctly
-- ⚠️ One-time effort but proper long-term solution
-
-## Next Steps for Relationship Analysis
-
-The relationship analysis should:
-
-1. **Parse local build template** (not just deployed template)
-2. **Detect CloudFormation Refs** in Lambda VPC configs
-3. **Resolve Refs to physical IDs** from deployed stack
-4. **Match orphaned resources** against resolved physical IDs
-5. **Identify import mapping**:
-   - `FriggVPC` (logical) → `vpc-0eadd96976d29ede7` (physical)
-   - `FriggPrivateSubnet1` → `subnet-00ab9e0502e66aac3`
-   - etc.
-
-This will enable `frigg repair --import` to:
-- Show correct VPC to import
-- Generate import-resources.json automatically
-- Handle CloudFormation import operation