@friggframework/devtools 2.0.0-next.5 → 2.0.0-next.51

package/frigg-cli/README.md

@@ -0,0 +1,1290 @@
+# Frigg CLI - Complete Documentation
+
+## Overview
+
+The Frigg CLI provides tools for building, deploying, and managing serverless integrations on cloud platforms. Built with Domain-Driven Design and Hexagonal Architecture for multi-cloud extensibility.
+
+---
+
+## Command Reference
+
+### Core Commands
+
+#### `frigg init [options]`
+
+**Status:** To be documented (command may not be merged yet)
+
+Initialize a new Frigg application with scaffolding and configuration.
+
+**Usage:**
+```bash
+frigg init
+frigg init my-app
+frigg init --template typescript
+```
+
+**What it does:**
+- TBD - Full documentation pending implementation merge
+
+**Options:**
+- TBD
+
+**Example Output:**
+- TBD
+
+> **Note**: This command may be part of an upcoming release. Documentation will be updated once the implementation is merged to the main branch.
+
+---
+
+#### `frigg install <module-name>`
+
+Install and configure an API integration module from the Frigg module library.
+
+**Usage:**
+```bash
+frigg install hubspot
+frigg install salesforce
+frigg install stripe
+```
+
+**What it does:**
+- Searches the api-module-library for the specified integration
+- Installs the npm package (@friggframework/api-module-{name})
+- Adds integration to your app definition
+- Configures OAuth flows and webhooks if applicable
+- Creates integration-specific environment variable placeholders
+
+**Options:**
+- None currently (could add `--version`, `--registry` in future)
+
+**Example Output:**
+```
+🔍 Finding integration module: hubspot
+✓ Found @friggframework/api-module-hubspot@2.0.5
+📦 Installing package...
+✓ Package installed successfully
+🔧 Configuring integration in app definition...
+✓ Integration configured
+⚙️  Next steps:
+   1. Set HUBSPOT_CLIENT_ID in your environment
+   2. Set HUBSPOT_CLIENT_SECRET in your environment
+   3. Run 'frigg start' to test locally
+```
+
+---
+
+#### `frigg search <term>`
+
+Search for available API integration modules.
+
+**Usage:**
+```bash
+frigg search crm
+frigg search payment
+frigg search
+```
+
+**What it does:**
+- Queries the api-module-library directory
+- Filters modules by name, description, or category
+- Returns list of matching integrations with metadata
+
+**Options:**
+- None (searches all if no term provided)
+
+**Example Output:**
+```
+📚 Available API Modules:
+
+CRM Systems:
+  • hubspot - HubSpot CRM & Marketing automation
+  • salesforce - Salesforce CRM & Sales Cloud
+  • pipedrive - Pipedrive sales CRM
+
+Payment Processing:
+  • stripe - Stripe payment processing
+  • square - Square payments & POS
+
+Found 5 modules matching "crm"
+```
+
+---
+
+#### `frigg start [options]`
+
+Start local development server with hot reload.
+
+**Usage:**
+```bash
+frigg start
+frigg start --stage dev
+frigg start --verbose
+frigg start --frontend
+```
+
+**What it does:**
+1. Validates DATABASE_URL environment variable
+2. Detects database type (MongoDB or PostgreSQL)
+3. Checks Prisma client generation status
+4. Tests database connection
+5. Starts serverless-offline for backend
+6. Optionally starts frontend dev server
+
+**Options:**
+- `--stage <stage>` - Deployment stage (default: 'dev')
+- `--verbose` - Enable verbose logging
+- `--frontend` - Also start frontend dev server
+- `--port <port>` - Backend port (default: 3000)
+- `--frontend-port <port>` - Frontend port (default: 3001)
+
+**Example Output:**
+```
+🚀 Starting Frigg application...
+✓ DATABASE_URL found
+✓ Database type: mongodb
+✓ Prisma client generated
+✓ Database connection successful
+
+Starting backend and optional frontend...
+Starting backend in /Users/dev/my-app/backend...
+
+╔═════════════════════════════════════════════════╗
+║                                                 ║
+║   Serverless Offline listening on port 3000    ║
+║                                                 ║
+╚═════════════════════════════════════════════════╝
+
+endpoints:
+  GET  - http://localhost:3000/health
+  POST - http://localhost:3000/api/authorize
+  POST - http://localhost:3000/api/webhook
+  ...
+```
+
+**Database Checks:**
+- Validates DATABASE_URL exists and is accessible
+- Determines database type from connection string
+- Verifies Prisma client is generated for the correct database
+- Tests connection with timeout
+- Provides helpful error messages for connection failures
+
+---
+
+#### `frigg deploy [options]`
+
+Deploy serverless infrastructure to cloud provider.
+
+**Usage:**
+```bash
+frigg deploy
+frigg deploy --stage production
+frigg deploy --region us-west-2
+frigg deploy --force
+frigg deploy --skip-env-validation
+frigg deploy --skip-doctor              # Skip health check (not recommended)
+frigg deploy --no-interactive           # CI/CD mode (no prompts, auto-repair safe issues)
+```
+
+**What it does:**
+1. **Runs health check** (`frigg doctor`) to detect infrastructure issues
+2. **Auto-repairs safe issues** (or prompts for confirmation in interactive mode)
+3. **Fails if critical issues found** (unless `--skip-doctor` flag used)
+4. Loads app definition from index.js
+5. Validates required environment variables
+6. Discovers existing cloud resources (VPC, KMS, Aurora, etc.)
+7. Makes ownership decisions (resources managed in CloudFormation stack)
+8. Generates CloudFormation resources
+9. Generates serverless.yml configuration
+10. Executes `osls deploy` with filtered environment
+11. Creates/updates stack in cloud provider
+
+**Options:**
+- `--stage <stage>` - Deployment stage (default: 'dev')
+- `--region <region>` - Cloud provider region (overrides app definition)
+- `--force` - Force deployment even if no changes detected
+- `--skip-env-validation` - Skip environment variable validation warnings
+- `--skip-doctor` - Skip infrastructure health check ⚠️ Not recommended
+- `--no-interactive` - Non-interactive mode for CI/CD (auto-repair safe issues, fail on risky changes)
+- `--verbose` - Enable verbose logging
+
+**Example Output:**
+```
+🔧 Loading environment configuration from appDefinition...
+   Found 3 environment variables: DATABASE_URL, JWT_SECRET, STRIPE_API_KEY
+
+🔍 Discovering existing infrastructure...
+
+[VPC Builder] Discovering VPC resources...
+  Found VPC: vpc-0abc123def456 (existing in AWS)
+  📋 Resource Ownership Decision: external - Using existing VPC vpc-0abc123def456
+[VPC Builder] ✅ VPC configuration completed
+
+[KMS Builder] Discovering KMS keys...
+  Found KMS key: alias/frigg-my-app-dev
+  📋 Resource Ownership Decision: stack - Will create FriggKMSKey in stack
+[KMS Builder] ✅ KMS configuration completed
+
+[Aurora Builder] Discovering Aurora clusters...
+  No existing Aurora cluster found
+  📋 Resource Ownership Decision: stack - Will create AuroraCluster in stack
+[Aurora Builder] ✅ Aurora configuration completed
+
+🚀 Deploying serverless application...
+
+Deploying my-app to stage dev (us-east-1)
+
+Creating CloudFormation stack...
+✓ Stack created: my-app-dev
+✓ VPC endpoints configured
+✓ Aurora cluster created
+✓ Lambda functions deployed (12)
+✓ API Gateway configured
+✓ CloudWatch alarms created
+
+Stack Outputs:
+  ServiceEndpoint: https://abc123.execute-api.us-east-1.amazonaws.com/dev
+  AuroraEndpoint: my-app-dev.cluster-abc123.us-east-1.rds.amazonaws.com
+
+Deployment completed in 3m 42s
+```
+
+**Environment Variable Handling:**
+- Passes only necessary environment variables to serverless (security)
+- Includes AWS credentials (AWS_* prefix)
+- Includes app-defined environment variables from definition
+- Validates required variables exist
+- Warns about missing optional variables
+
+**Resource Ownership:**
+- Resources can be marked as `STACK` (managed in CloudFormation) or `EXTERNAL` (use existing by ID)
+- Default behavior: manage resources in CloudFormation stack for full lifecycle control
+- Doctor/repair handles edge cases (orphaned resources, drift) before deployment
+- Explicit ownership in app definition recommended for production
+
+**CI/CD Deployment:**
+- Use `--no-interactive` flag to prevent prompts
+- Deployment will auto-fix safe issues (mutable property drift)
+- Deployment will **fail fast** on risky issues (orphaned resources, immutable property changes)
+- Prevents stack rollbacks and 2+ hour waits from bad deployments
+- Returns non-zero exit code if issues require manual intervention
+
+**Example CI/CD Pipeline:**
+```yaml
+# GitHub Actions / GitLab CI / etc.
+- name: Deploy to production
+  run: |
+    frigg deploy \
+      --stage production \
+      --no-interactive \
+      --skip-env-validation
+  env:
+    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+    DATABASE_URL: ${{ secrets.DATABASE_URL }}
+```
+
+---
+
+#### `frigg db:setup [options]`
+
+Initialize database and Prisma configuration.
+
+**Usage:**
+```bash
+frigg db:setup
+frigg db:setup --mongodb
+frigg db:setup --postgresql
+frigg db:setup --generate-only
+```
+
+**What it does:**
+1. Detects database type from DATABASE_URL or option
+2. Validates DATABASE_URL format
+3. Generates Prisma client for the detected database type
+4. Tests database connection
+5. Pushes Prisma schema to database (creates tables/collections)
+6. Runs any pending data migrations
+
+**Options:**
+- `--mongodb` - Force MongoDB configuration
+- `--postgresql` - Force PostgreSQL configuration
+- `--generate-only` - Only generate Prisma client, don't push schema
+- `--skip-connection-test` - Skip database connection validation
+
+**Example Output:**
+```
+🗄️  Setting up database...
+✓ DATABASE_URL found
+✓ Database type detected: mongodb
+✓ Generating Prisma client for mongodb...
+✓ Prisma client generated successfully
+✓ Testing database connection...
+✓ Connection successful
+✓ Pushing schema to database...
+✓ Database schema synchronized
+
+Database setup complete!
+```
+
+**Error Handling:**
+- Validates DATABASE_URL format for each database type
+- Tests connection before attempting schema push
+- Provides helpful error messages for:
+  - Connection timeout
+  - Invalid credentials
+  - Network issues
+  - Schema validation errors
+- Suggests fixes based on error type
+
+---
+
+#### `frigg generate <type> <name>`
+
+Generate boilerplate code for integrations, handlers, or tests.
+
+**Usage:**
+```bash
+frigg generate integration shopify
+frigg generate handler payment-webhook
+frigg generate test integration-shopify
+```
+
+**What it does:**
+- Creates file structure from templates
+- Generates TypeScript or JavaScript based on project
+- Includes proper imports and exports
+- Follows Frigg framework conventions
+- Updates relevant configuration files
+
+**Types:**
+- `integration` - New integration module
+- `handler` - API handler/route
+- `test` - Test file
+- `migration` - Database migration
+
+**Options:**
+- `--typescript` - Generate TypeScript files
+- `--javascript` - Generate JavaScript files
+- `--template <name>` - Use specific template
+
+**Example Output:**
+```
+✨ Generating integration: shopify
+
+Created files:
+  ✓ backend/integrations/shopify/index.js
+  ✓ backend/integrations/shopify/api.js
+  ✓ backend/integrations/shopify/config.js
+  ✓ backend/integrations/shopify/definition.js
+  ✓ backend/integrations/shopify/__tests__/integration.test.js
+
+Updated files:
+  ✓ backend/index.js (added integration import)
+
+Next steps:
+  1. Configure OAuth settings in definition.js
+  2. Implement API methods in api.js
+  3. Add integration to app definition
+  4. Run tests: npm test shopify
+```
+
+---
+
+### New Infrastructure Health Commands
+
+#### `frigg doctor [options]`
+
+**Status:** Planned (implementation in progress)
+
+Run comprehensive health check on deployed infrastructure.
+
+**Usage:**
+```bash
+frigg doctor
+frigg doctor --stack my-app-prod
+frigg doctor --region us-west-2
+frigg doctor --verbose
+frigg doctor --format json
+```
+
+**What it does:**
+1. Discovers resources in CloudFormation stack
+2. Discovers resources in cloud provider (AWS/GCP/Azure)
+3. Compares desired state (app definition) with actual state
+4. Detects infrastructure issues:
+   - **Orphaned Resources** - Resources exist in cloud but not in stack
+   - **Missing Resources** - Resources defined in stack but don't exist
+   - **Drifted Resources** - Properties differ between stack and actual
+   - **Property Mismatches** - Configuration drift on specific properties
+5. Calculates health score (0-100)
+6. Provides actionable remediation suggestions
+
+**Options:**
+- `--stack <name>` - CloudFormation stack name (default: from app definition)
+- `--region <region>` - Cloud provider region
+- `--format <format>` - Output format: `table` (default), `json`, `yaml`
+- `--verbose` - Show detailed property comparisons
+- `--check <domain>` - Check specific domain only: `vpc`, `kms`, `aurora`, `all`
+- `--exit-code` - Exit with non-zero code if unhealthy (for CI/CD)
+
+**Example Output:**
+
+```
+🩺 Running infrastructure health check...
+
+Stack: my-app-prod (us-east-1)
+Region: us-east-1
+Account: 123456789012
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+HEALTH SCORE: 65 (degraded)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Resource Summary
+  ✓ 12 resources healthy
+  ⚠  3 resources with warnings
+  ✗ 2 critical issues
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 CRITICAL ISSUES (2)
+
+[1] Orphaned Resource
+    Type: AWS::RDS::DBCluster
+    Physical ID: my-app-prod-aurora-cluster
+    Status: ORPHANED
+    Issue: Resource exists in AWS but not managed by CloudFormation stack
+    Impact: Stack doesn't track this resource. Manual deletion could break app.
+
+    Resolution: Run 'frigg repair --import' to import into stack
+
+[2] Property Mismatch (Immutable)
+    Resource: ProductionBucket (AWS::S3::Bucket)
+    Property: BucketName
+    Expected: my-app-prod-bucket-v2
+    Actual: my-app-prod-bucket-v1
+    Mutability: IMMUTABLE
+    Impact: Requires resource replacement to fix
+
+    Resolution: Run 'frigg repair --reconcile' to plan replacement
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⚠️  WARNINGS (3)
+
+[1] Property Drift (Mutable)
+    Resource: ProdVPC (AWS::EC2::VPC)
+    Property: Tags
+    Expected: [{"Key": "Environment", "Value": "production"}]
+    Actual: [{"Key": "Env", "Value": "prod"}]
+    Mutability: MUTABLE
+    Impact: Configuration drift - can be auto-fixed
+
+    Resolution: Run 'frigg repair --reconcile'
+
+[2] Property Drift (Mutable)
+    Resource: FriggKMSKey (AWS::KMS::Key)
+    Property: EnableKeyRotation
+    Expected: true
+    Actual: false
+    Mutability: MUTABLE
+    Impact: Key rotation disabled - security risk
+
+    Resolution: Run 'frigg repair --reconcile'
+
+[3] Missing Tag
+    Resource: LambdaExecutionRole (AWS::IAM::Role)
+    Expected Tag: CostCenter
+    Impact: Cost tracking incomplete
+
+    Resolution: Update app definition and redeploy
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+💡 RECOMMENDATIONS
+
+High Priority:
+  • Import orphaned Aurora cluster to prevent data loss
+  • Plan S3 bucket replacement (requires downtime)
+
+Medium Priority:
+  • Fix 2 mutable property drifts
+  • Enable KMS key rotation for security
+
+Low Priority:
+  • Add missing tags for cost tracking
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next steps:
+  1. Review critical issues above
+  2. Run 'frigg repair' to fix detected issues
+  3. Re-run 'frigg doctor' to verify fixes
+
+For detailed report: frigg doctor --format json > health-report.json
+```
+
+**JSON Output** (with `--format json`):
+```json
+{
+  "stack": {
+    "name": "my-app-prod",
+    "region": "us-east-1",
+    "accountId": "123456789012"
+  },
+  "healthScore": 65,
+  "assessment": "degraded",
+  "summary": {
+    "healthy": 12,
+    "warnings": 3,
+    "critical": 2,
+    "total": 17
+  },
+  "issues": [
+    {
+      "severity": "critical",
+      "type": "orphaned_resource",
+      "resource": {
+        "type": "AWS::RDS::DBCluster",
+        "physicalId": "my-app-prod-aurora-cluster",
+        "state": "ORPHANED"
+      },
+      "description": "Resource exists in AWS but not managed by stack",
+      "impact": "Stack doesn't track this resource",
+      "resolution": {
+        "command": "frigg repair --import",
+        "canAutoFix": true
+      }
+    },
+    {
+      "severity": "critical",
+      "type": "property_mismatch",
+      "resource": {
+        "logicalId": "ProductionBucket",
+        "type": "AWS::S3::Bucket",
+        "physicalId": "my-app-prod-bucket-v1"
+      },
+      "mismatch": {
+        "propertyPath": "Properties.BucketName",
+        "expected": "my-app-prod-bucket-v2",
+        "actual": "my-app-prod-bucket-v1",
+        "mutability": "IMMUTABLE"
+      },
+      "impact": "Requires resource replacement",
+      "resolution": {
+        "command": "frigg repair --reconcile",
+        "canAutoFix": false,
+        "requiresReplacement": true
+      }
+    }
+  ],
+  "recommendations": [
+    {
+      "priority": "high",
+      "action": "Import orphaned Aurora cluster",
+      "reason": "Prevent data loss"
+    },
+    {
+      "priority": "high",
+      "action": "Plan S3 bucket replacement",
+      "reason": "Requires downtime coordination"
+    }
+  ],
+  "timestamp": "2025-10-26T01:23:45.678Z"
+}
+```
+
+**Exit Codes** (with `--exit-code`):
+- `0` - Healthy (score >= 80)
+- `1` - Degraded (score 40-79)
+- `2` - Unhealthy (score < 40)
+- `3` - Error running health check
+
+**Use Cases:**
+- **Pre-deployment validation** - Run before deploy to catch issues
+- **CI/CD health gates** - Fail pipeline if score below threshold
+- **Scheduled audits** - Cron job to monitor infrastructure drift
+- **Incident investigation** - Diagnose production issues
+- **Compliance checks** - Verify security configurations
+
+---
+
+#### `frigg repair [options]`
+
+**Status:** Planned (implementation in progress)
+
+Repair infrastructure issues detected by `frigg doctor`.
+
+**Usage:**
+```bash
+frigg repair                              # Interactive mode
+frigg repair --import                     # Import orphaned resources
+frigg repair --reconcile                  # Fix property mismatches
+frigg repair --clean-deploy               # Delete and recreate resources
+frigg repair --auto                       # Auto-fix all fixable issues (CI/CD mode)
+frigg repair --dry-run                    # Show what would be fixed
+frigg repair --issue <id>                 # Fix specific issue only
+```
+
+**What it does:**
+
+**Import Mode** (`--import`):
+1. Discovers orphaned resources (exist in cloud, not in stack)
+2. Validates resources are importable
+3. Generates CloudFormation import change set
+4. Displays resources to be imported
+5. Confirms with user (unless --auto)
+6. Executes CloudFormation import operation
+7. Updates stack to track resources
+
+**Reconcile Mode** (`--reconcile`):
+1. Detects property mismatches (drift)
+2. Categorizes by mutability:
+   - **Mutable** - Can update without replacement
+   - **Immutable** - Requires resource replacement
+   - **Conditional** - Depends on other properties
+3. Auto-fixes mutable properties
+4. Plans replacement for immutable properties
+5. Prompts for confirmation on destructive changes
+6. Executes updates via CloudFormation
+
+**Clean Deploy Mode** (`--clean-deploy`):
+1. Identifies resources that can't be imported/reconciled
+2. Plans deletion of problematic resources
+3. Generates new resource definitions
+4. Confirms destructive operation
+5. Deletes old resources
+6. Creates new resources via CloudFormation
+7. Updates application references
+
+**Options:**
+- `--import` - Import orphaned resources into stack
+- `--reconcile` - Fix property mismatches
+- `--clean-deploy` - Delete and recreate resources
+- `--auto` - Auto-fix without prompts (for CI/CD)
+- `--dry-run` - Show planned changes without executing
+- `--issue <id>` - Fix only specific issue from doctor report
+- `--force` - Skip safety checks (dangerous!)
+- `--backup` - Create backup before destructive operations
+
+**Example Output:**
+
+**Interactive Mode:**
+```
+🔧 Frigg Repair - Infrastructure Remediation
+
+🩺 Running health check first...
+Found 5 issues to repair:
+  • 2 orphaned resources
+  • 2 property mismatches (mutable)
+  • 1 property mismatch (immutable)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What would you like to do?
+
+[1] Import orphaned resources (2)
+    ├─ AWS::RDS::DBCluster - my-app-prod-aurora-cluster
+    └─ AWS::EC2::VPC - vpc-0abc123
+
+[2] Fix mutable property drift (2) ⚡ Auto-fixable
+    ├─ ProdVPC: Tags property mismatch
+    └─ FriggKMSKey: EnableKeyRotation mismatch
+
+[3] Plan immutable property replacement (1) ⚠️  Requires downtime
+    └─ ProductionBucket: BucketName mismatch
+
+[4] Fix all auto-fixable issues
+[5] Show detailed repair plan
+[Q] Quit
+
+Select option [1-5, Q]:
+```
+
+**After selecting option 1 (Import):**
+```
+🔍 Analyzing resources for import...
+
+Resources to import:
+┌──────────────────────────────────────────────────────────────┐
+│ Resource 1: Aurora Database Cluster                         │
+├──────────────────────────────────────────────────────────────┤
+│ Type:        AWS::RDS::DBCluster                            │
+│ Physical ID: my-app-prod-aurora-cluster                     │
+│ Logical ID:  AuroraCluster (will be assigned)              │
+│ Status:      Ready for import                               │
+│ Properties:  Will be matched from existing resource         │
+└──────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────┐
+│ Resource 2: VPC                                             │
+├──────────────────────────────────────────────────────────────┤
+│ Type:        AWS::EC2::VPC                                  │
+│ Physical ID: vpc-0abc123                                    │
+│ Logical ID:  ProdVPC (will be assigned)                    │
+│ Status:      Ready for import                               │
+│ Properties:  Will be matched from existing resource         │
+└──────────────────────────────────────────────────────────────┘
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⚠️  IMPORTANT: CloudFormation Import Requirements
+
+✓ Resources must be in a stable state
+✓ Resources must be importable resource types
+✓ Stack must be in UPDATE_COMPLETE or CREATE_COMPLETE state
+✓ Import operation cannot be rolled back
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Proceed with import? [y/N]: y
+
+Creating CloudFormation change set for import...
+✓ Change set created: import-2025-10-26-01-23-45
+
+Reviewing change set...
+✓ Validation passed
+
+Executing import operation...
+[████████████████████████████████] 100% - Importing resources
+
+✓ AuroraCluster imported successfully
+✓ ProdVPC imported successfully
+
+Import completed! Resources are now managed by CloudFormation.
+
+Next steps:
+  • Run 'frigg doctor' to verify health improved
+  • Future deploys will manage these resources
+```
+
+**After selecting option 2 (Fix Mutable Drift):**
+```
+🔄 Reconciling property mismatches...
+
+Planned Updates:
+┌──────────────────────────────────────────────────────────────┐
+│ Update 1: ProdVPC (AWS::EC2::VPC)                           │
+├──────────────────────────────────────────────────────────────┤
+│ Property: Tags                                              │
+│ Current:  [{"Key": "Env", "Value": "prod"}]                │
+│ Desired:  [{"Key": "Environment", "Value": "production"}]  │
+│ Impact:   No interruption                                   │
+│ Auto-fix: ✓ Yes                                             │
+└──────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────┐
+│ Update 2: FriggKMSKey (AWS::KMS::Key)                      │
+├──────────────────────────────────────────────────────────────┤
+│ Property: EnableKeyRotation                                 │
+│ Current:  false                                             │
+│ Desired:  true                                              │
+│ Impact:   No interruption                                   │
+│ Auto-fix: ✓ Yes                                             │
+└──────────────────────────────────────────────────────────────┘
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+These changes are safe (no resource replacement required).
+
+Proceed with updates? [y/N]: y
+
+Applying updates via CloudFormation...
+[████████████████████████████████] 100% - Updating stack
+
+✓ ProdVPC tags updated
+✓ FriggKMSKey rotation enabled
+
+Property drift fixed! Stack now matches desired configuration.
+```
+
+**Dry Run Mode** (`--dry-run`):
+```
+🔬 Repair Dry Run - No changes will be made
+
+Detected Issues:
+  ✓ 2 orphaned resources → Would import via CloudFormation
+  ✓ 2 mutable property drifts → Would update properties
+  ✗ 1 immutable property drift → Requires manual intervention
+
+Planned Actions:
+
+[1] Import Resources
+    Command: aws cloudformation create-change-set \
+      --stack-name my-app-prod \
+      --change-set-type IMPORT \
+      --resources-to-import file://resources.json
+
+[2] Update Properties
+    Update: ProdVPC.Tags
+      From: [{"Key": "Env", "Value": "prod"}]
+      To:   [{"Key": "Environment", "Value": "production"}]
+
+    Update: FriggKMSKey.EnableKeyRotation
+      From: false
+      To:   true
+
+[3] Manual Action Required
+    Resource: ProductionBucket
+    Issue: BucketName is immutable
+    Current: my-app-prod-bucket-v1
+    Desired: my-app-prod-bucket-v2
+
+    Resolution steps:
+      1. Create new bucket: my-app-prod-bucket-v2
+      2. Copy data from old bucket to new bucket
+      3. Update application configuration
+      4. Delete old bucket: my-app-prod-bucket-v1
+      5. Update CloudFormation stack
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+To execute repairs, run: frigg repair --auto
+To execute specific issue: frigg repair --issue <id>
+```
+
+**Exit Codes:**
+- `0` - Repairs completed successfully
+- `1` - Some repairs failed
+- `2` - Repairs require manual intervention
+- `3` - Error during repair operation
+
+**Safety Features:**
+- **Confirmation prompts** for destructive operations
+- **Dry-run mode** to preview changes
+- **Backup creation** before deletions
+- **Rollback support** via CloudFormation
+- **Validation** before import/update
+- **Issue-specific** repair to limit blast radius
+
+**Use Cases:**
+- **Import unmanaged resources** - Bring existing infrastructure under CloudFormation management
+- **Fix configuration drift** - Align actual state with desired state
+- **Clean up orphaned resources** - Remove resources outside stack control
+- **Remediate security issues** - Fix misconfigurations automatically
+- **CI/CD integration** - Auto-repair in deployment pipelines
+
+---
+
+## Multi-Cloud Provider Support
+
+### Current Status
+- **AWS**: Fully supported
+- **GCP**: Planned
+- **Azure**: Planned
+- **Cloudflare**: Planned
+
+### Architecture for Multi-Cloud
+
+The CLI uses Hexagonal Architecture (Ports & Adapters) to support multiple cloud providers:
+
+**Domain Layer** (Provider-Agnostic):
+```
+packages/devtools/infrastructure/domains/health/
+  domain/           # Pure domain logic (no provider specifics)
+    entities/       # Resource, Issue, StackHealthReport
+    value-objects/  # HealthScore, ResourceState, PropertyMutability
+    services/       # HealthScoreCalculator, DriftDetector
+
+  application/      # Use cases (orchestration)
+    use-cases/      # RunHealthCheck, RepairStack, ImportResource
+    ports/          # Interfaces for adapters
+      StackRepository.js         # Port interface
+      ResourceDetector.js        # Port interface
+      DriftDetector.js           # Port interface
+```
+
+**Infrastructure Layer** (Provider-Specific Adapters):
+```
+packages/devtools/infrastructure/domains/health/
+  infrastructure/
+    adapters/
+      aws/          # AWS-specific implementations
+        AWSStackRepository.js         # CloudFormation
+        AWSResourceDetector.js        # AWS APIs (EC2, RDS, etc.)
+        AWSCloudFormationImporter.js  # Import operations
+
+      gcp/          # GCP-specific implementations (future)
+        GCPStackRepository.js         # Deployment Manager
+        GCPResourceDetector.js        # GCP APIs
+        GCPDeploymentImporter.js
+
+      azure/        # Azure-specific implementations (future)
+        AzureStackRepository.js       # ARM Templates
+        AzureResourceDetector.js      # Azure APIs
+        AzureResourceImporter.js
+```
+
+**Provider Selection**:
+```javascript
+// App definition specifies provider
+{
+  provider: 'aws',  // or 'gcp', 'azure', 'cloudflare'
+  region: 'us-east-1',
+  // ... rest of definition
+}
+
+// CLI auto-selects correct adapter
+const adapters = getAdaptersForProvider(appDefinition.provider);
+const useCase = new RunHealthCheckUseCase({
+  stackRepository: adapters.stackRepository,      // AWS/GCP/Azure
+  resourceDetector: adapters.resourceDetector,    // Provider-specific
+  driftDetector: adapters.driftDetector,          // Provider-specific
+});
+```
+
+**Provider-Specific Domains**:
+
+Some infrastructure domains are inherently provider-specific:
+
+```
+domains/
+  networking/
+    vpc-builder.js              # AWS VPC
+    vnet-builder.js             # Azure VNet (future)
+    network-builder.js          # GCP Network (future)
+
+  database/
+    aurora-builder.js           # AWS Aurora
+    cloud-sql-builder.js        # GCP Cloud SQL (future)
+    cosmos-db-builder.js        # Azure Cosmos DB (future)
+```
+
+Builder orchestrator selects appropriate builders based on provider:
+```javascript
+const orchestrator = new BuilderOrchestrator(
+  getBuilders(appDefinition.provider) // Returns AWS/GCP/Azure builders
+);
+```
+
+---
+
+## Environment Variables
+
+### Required (varies by features used)
+
+**Database:**
+- `DATABASE_URL` - Connection string for MongoDB or PostgreSQL
+
+**AWS Deployment:**
+- `AWS_ACCESS_KEY_ID` - AWS access key
+- `AWS_SECRET_ACCESS_KEY` - AWS secret key
+- `AWS_REGION` - AWS region (or use --region flag)
+
+**Encryption:**
+- `KMS_KEY_ARN` - AWS KMS key ARN (or auto-discovered)
+- `AES_KEY_ID` - AES key ID (if using AES encryption)
+- `AES_KEY` - AES encryption key (32 characters)
+
+**Optional:**
+- `STAGE` - Deployment stage (default: 'dev')
+- `FRIGG_SKIP_AWS_DISCOVERY` - Skip AWS resource discovery (speeds up local dev)
+- `NODE_ENV` - Node environment (development, production, test)
+
+### App-Defined Variables
+
+Additional environment variables can be defined in your app definition:
+
+```javascript
+{
+  environment: {
+    JWT_SECRET: true,           // Mark as required
+    STRIPE_API_KEY: true,
+    SENDGRID_API_KEY: true,
+    FEATURE_FLAG_X: true,
+  }
+}
+```
+
+These are validated during deploy and passed to Lambda functions.
+
+---
+
+## Configuration Files
+
+### `index.js` (App Definition)
+
+Entry point for your Frigg application:
+
+```javascript
+const { ModuleManager, IntegrationManager } = require('@friggframework/core');
+const HubSpotIntegration = require('@friggframework/api-module-hubspot');
+
+const Definition = {
+  name: 'my-integration-app',
+  version: '1.0.0',
+
+  provider: 'aws',
+  region: 'us-east-1',
+
+  integrations: [
+    {
+      Definition: HubSpotIntegration.Definition,
+      ownership: {
+        queue: 'STACK',  // Create queue in CloudFormation
+      },
+    },
+  ],
+
+  database: {
+    type: 'mongodb',
+    ownership: 'STACK',  // Create Aurora in CloudFormation
+  },
+
+  vpc: {
+    ownership: 'EXTERNAL',
+    vpcId: 'vpc-0abc123',  // Use existing VPC
+  },
+
+  kms: {
+    ownership: 'STACK',  // Create KMS key in CloudFormation
+  },
+
+  encryption: {
+    useDefaultKMSForFieldLevelEncryption: true,
+  },
+
+  environment: {
+    DATABASE_URL: true,
+    JWT_SECRET: true,
+  },
+};
+
+module.exports = { Definition };
+```
+
+### `infrastructure.js` (Generated)
+
+This file is **generated** by the Frigg infrastructure composer and should not be edited manually. It's referenced by `osls deploy` command.
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Frigg CLI Commands                                      │
+│  • frigg install     • frigg deploy    • frigg doctor   │
+│  • frigg search      • frigg start     • frigg repair   │
+│  • frigg generate    • frigg db:setup                   │
+└───────────────┬─────────────────────────────────────────┘
+                │
+┌───────────────▼─────────────────────────────────────────┐
+│ Infrastructure Composer                                 │
+│  packages/devtools/infrastructure/                      │
+│                                                         │
+│  • Loads app definition (index.js)                     │
+│  • Orchestrates domain builders                        │
+│  • Generates serverless configuration                  │
+└───────────────┬─────────────────────────────────────────┘
+                │
+┌───────────────▼─────────────────────────────────────────┐
+│ Domain Builders (Hexagonal Architecture)               │
+│                                                         │
+│  Discovery → Resolution → Building                     │
+│                                                         │
+│  • VpcBuilder         (networking)                     │
+│  • KmsBuilder         (security)                       │
+│  • AuroraBuilder      (database)                       │
+│  • MigrationBuilder   (database)                       │
+│  • IntegrationBuilder (integration)                    │
+│  • SsmBuilder         (parameters)                     │
+│  • WebsocketBuilder   (integration)                    │
+└───────────────┬─────────────────────────────────────────┘
+                │
+┌───────────────▼─────────────────────────────────────────┐
+│ OSS-Serverless (Deployment)                            │
+│  • Packages Lambda functions                           │
+│  • Generates CloudFormation templates                  │
+│  • Deploys to AWS                                      │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Common Workflows
+
+### Initial Project Setup
+
+```bash
+# 1. Install integrations
+frigg install hubspot
+frigg install stripe
+
+# 2. Set up database
+export DATABASE_URL="mongodb://localhost:27017/myapp"
+frigg db:setup
+
+# 3. Start local development
+frigg start --frontend
+
+# 4. Test integration flows locally
+# Visit http://localhost:3000
+
+# 5. Deploy to dev
+frigg deploy --stage dev
+
+# 6. Deploy to production
+frigg deploy --stage production
+```
+
+### Infrastructure Health Workflow
+
+```bash
+# 1. Check infrastructure health
+frigg doctor --stage production
+
+# 2. Review issues (health score, orphaned resources, drift)
+
+# 3. Fix auto-fixable issues
+frigg repair --auto
+
+# 4. Manually fix complex issues
+frigg repair --issue 3
+
+# 5. Verify health improved
+frigg doctor --stage production
+```
+
+### Troubleshooting Deployment Issues
+
+```bash
+# 1. Enable verbose logging
+frigg deploy --stage dev --verbose
+
+# 2. Check for orphaned resources
+frigg doctor --verbose
+
+# 3. Import orphaned resources
+frigg repair --import
+
+# 4. Retry deployment
+frigg deploy --stage dev --force
+```
+
+---
+
+## Exit Codes
+
+All commands follow consistent exit code conventions:
+
+- `0` - Success
+- `1` - General error
+- `2` - Configuration error
+- `3` - Network/API error
+- `4` - Validation error
+- `5` - User cancelled operation
+
+---
+
+## Getting Help
+
+```bash
+frigg --help                  # General help
+frigg <command> --help        # Command-specific help
+frigg --version               # Show version
+```
+
+**Community Support:**
+- GitHub Issues: https://github.com/friggframework/frigg/issues
+- Documentation: https://docs.friggframework.org
+- Slack: Join via https://friggframework.org/#contact
+
+---
+
+## Package Structure & Global Installation
+
+### Overview
+
+The Frigg CLI is a standalone globally-installable npm package that can be installed via `npm i -g @friggframework/frigg-cli`. It includes version detection logic to automatically prefer local project installations when available.
+
+### Package Structure
+
+**@friggframework/frigg-cli** (standalone package)
+```
+├── package.json
+│   ├── dependencies: @friggframework/core@^2.0.0-next.0
+│   ├── dependencies: @friggframework/devtools@^2.0.0-next.0
+│   └── publishConfig: { access: "public" }
+└── index.js (with version detection wrapper)
+```
+
+**Key Changes from Previous Structure:**
+- ✅ Replaced `workspace:*` with concrete versions (`^2.0.0-next.0`)
+- ✅ Added `@friggframework/devtools` as dependency
+- ✅ Added `publishConfig` for public npm publishing
+- ✅ Removed bin entry from devtools package.json
+
+**Note:** Since `@friggframework/devtools` is a dependency, the global install size includes devtools. The main benefit is proper version resolution (no `workspace:*` errors) and automatic local CLI preference.
+
+### Version Detection Logic
+
+When you run `frigg` (globally installed), the CLI:
+
+1. **Checks for skip flag**
+   - If `FRIGG_CLI_SKIP_VERSION_CHECK=true`, skips detection (prevents recursion)
+
+2. **Looks for local installation**
+   - Searches for `node_modules/@friggframework/frigg-cli` in current directory
+
+3. **Compares versions**
+   - Uses `semver.compare(localVersion, globalVersion)`
+
+4. **Makes decision**:
+   - **Local ≥ Global**: Uses local CLI (spawns subprocess)
+   - **Global > Local**: Warns and uses global
+   - **No local**: Uses global silently
+
+### Benefits
+
+| Aspect | Before | After |
+|--------|--------|-------|
+| **Global Install** | `npm i -g @friggframework/devtools` | `npm i -g @friggframework/frigg-cli` |
+| **Dependencies** | workspace:* (broken) | Concrete versions (works) |
+| **Version Preference** | No detection | Automatic local preference |
+| **Version Warnings** | None | Mismatch alerts |
+| **Publishability** | ❌ Fails | ✅ Works |
+| **Local Project Isolation** | ❌ Uses global versions | ✅ Uses local versions when available |
+
+### Publishing Workflow
+
+```bash
+# Publish to npm
+cd packages/frigg-cli
+npm version patch  # or minor, major
+npm publish
+
+# Users can now install globally
+npm install -g @friggframework/frigg-cli
+
+# And it will automatically use local versions when available
+```
+
+### Migration Path
+
+**For existing users:**
+
+```bash
+# Step 1: Uninstall old global devtools
+npm uninstall -g @friggframework/devtools
+
+# Step 2: Install new global CLI
+npm install -g @friggframework/frigg-cli
+
+# Step 3: Update local project dependencies
+npm install @friggframework/frigg-cli@latest
+```
+
+**For new projects:**
+
+```bash
+# Global CLI (once per machine)
+npm install -g @friggframework/frigg-cli
+
+# Local project dependencies
+npx create-frigg-app my-app
+# (Will automatically include @friggframework/frigg-cli in package.json)
+```
+
+**Status:** ✅ Complete and tested (15 passing tests)
+