@friggframework/devtools 2.0.0--canary.474.da7b114.0 → 2.0.0--canary.474.82ba370.0

package/frigg-cli/CLI.md

@@ -10,6 +10,32 @@ The Frigg CLI provides tools for building, deploying, and managing serverless in
 
 ### 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.
@@ -155,23 +181,30 @@ 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. Loads app definition from index.js
-2. Validates required environment variables
-3. Discovers existing cloud resources (VPC, KMS, Aurora, etc.)
-4. Makes ownership decisions (STACK vs EXTERNAL)
-5. Generates CloudFormation resources
-6. Generates serverless.yml configuration
-7. Executes `osls deploy` with filtered environment
-8. Creates/updates stack in cloud provider
+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:**
@@ -222,11 +255,33 @@ Deployment completed in 3m 42s
 - Validates required variables exist
 - Warns about missing optional variables
 
-**Resource Discovery:**
-- Queries CloudFormation for existing stack resources
-- Queries AWS APIs for VPC, subnets, security groups, KMS keys, Aurora clusters
-- Makes intelligent decisions about STACK vs EXTERNAL ownership
-- Uses AUTO logic to minimize user configuration
+**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 }}
+```
 
 ---
 
@@ -566,7 +621,7 @@ 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
+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
 ```

package/infrastructure/MULTI_CLOUD_ARCHITECTURE.md

@@ -197,444 +197,128 @@ packages/devtools/infrastructure/
 
 ## Port Interfaces (Contracts)
 
-### IStackRepository
+Port interfaces define the contracts that provider-specific adapters must implement. These are the boundaries between the provider-agnostic domain layer and provider-specific infrastructure.
 
-```javascript
-/**
- * Port: Stack Repository Interface
- *
- * Abstracts stack management operations (CloudFormation, Deployment Manager, ARM)
- */
-class IStackRepository {
-  /**
-   * Get stack by identifier
-   * @param {StackIdentifier} identifier
-   * @returns {Promise<Stack|null>}
-   */
-  async getStack(identifier) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * List resources in stack
-   * @param {StackIdentifier} identifier
-   * @returns {Promise<Resource[]>}
-   */
-  async listResources(identifier) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Get stack outputs
-   * @param {StackIdentifier} identifier
-   * @returns {Promise<Object>}
-   */
-  async getOutputs(identifier) {
-    throw new Error('Not implemented');
-  }
+**Source files**: `packages/devtools/infrastructure/domains/health/application/ports/`
 
-  /**
-   * Get stack parameters
-   * @param {StackIdentifier} identifier
-   * @returns {Promise<Object>}
-   */
-  async getParameters(identifier) {
-    throw new Error('Not implemented');
-  }
+### Key Ports
 
-  /**
-   * Check if stack exists
-   * @param {StackIdentifier} identifier
-   * @returns {Promise<boolean>}
-   */
-  async exists(identifier) {
-    throw new Error('Not implemented');
-  }
-}
+**IStackRepository** - Stack management operations (CloudFormation, Deployment Manager, ARM)
+```javascript
+// Example methods:
+async getStack(identifier)
+async listResources(identifier)
+async getOutputs(identifier)
 ```
+📄 See: `application/ports/IStackRepository.js`
 
-### IResourceDetector
-
+**IResourceDetector** - Cloud resource discovery (AWS APIs, GCP APIs, Azure APIs)
 ```javascript
-/**
- * Port: Resource Detector Interface
- *
- * Abstracts cloud resource discovery (AWS APIs, GCP APIs, Azure APIs)
- */
-class IResourceDetector {
-  /**
-   * Detect VPCs/Networks
-   * @param {string} region
-   * @returns {Promise<NetworkResource[]>}
-   */
-  async detectNetworks(region) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Detect database instances
-   * @param {string} region
-   * @returns {Promise<DatabaseResource[]>}
-   */
-  async detectDatabases(region) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Detect encryption keys
-   * @param {string} region
-   * @returns {Promise<KeyResource[]>}
-   */
-  async detectKeys(region) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Detect resource by physical ID
-   * @param {string} physicalId
-   * @param {string} resourceType
-   * @returns {Promise<Resource|null>}
-   */
-  async detectResourceById(physicalId, resourceType) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Get resource properties
-   * @param {string} physicalId
-   * @param {string} resourceType
-   * @returns {Promise<Object>}
-   */
-  async getResourceProperties(physicalId, resourceType) {
-    throw new Error('Not implemented');
-  }
-}
+// Example methods:
+async detectNetworks(region)
+async detectDatabases(region)
+async detectKeys(region)
+async detectResourceById(physicalId, resourceType)
 ```
+📄 See: `application/ports/IResourceDetector.js`
 
-### IDriftDetector
-
+**IDriftDetector** - Compare desired state vs actual state
 ```javascript
-/**
- * Port: Drift Detector Interface
- *
- * Abstracts drift detection logic
- */
-class IDriftDetector {
-  /**
-   * Detect drift for a resource
-   * @param {Resource} resource - Resource from stack
-   * @param {Object} desiredProperties - Desired properties
-   * @returns {Promise<PropertyMismatch[]>}
-   */
-  async detectDrift(resource, desiredProperties) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Detect drift for entire stack
-   * @param {StackIdentifier} identifier
-   * @returns {Promise<DriftDetectionResult>}
-   */
-  async detectStackDrift(identifier) {
-    throw new Error('Not implemented');
-  }
-}
+// Example methods:
+async detectDrift(resource, desiredProperties)
+async detectStackDrift(identifier)
 ```
+📄 See: `application/ports/IDriftDetector.js`
 
-### IResourceImporter
-
+**IResourceImporter** - Import existing resources into stack
 ```javascript
-/**
- * Port: Resource Importer Interface
- *
- * Abstracts resource import operations
- */
-class IResourceImporter {
-  /**
-   * Check if resource type is importable
-   * @param {string} resourceType
-   * @returns {boolean}
-   */
-  isImportable(resourceType) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Create import change set
-   * @param {StackIdentifier} stackId
-   * @param {Resource[]} resources
-   * @returns {Promise<ImportChangeSet>}
-   */
-  async createImportChangeSet(stackId, resources) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Execute import operation
-   * @param {ImportChangeSet} changeSet
-   * @returns {Promise<ImportResult>}
-   */
-  async executeImport(changeSet) {
-    throw new Error('Not implemented');
-  }
-}
+// Example methods:
+isImportable(resourceType)
+async createImportChangeSet(stackId, resources)
+async executeImport(changeSet)
 ```
+📄 See: `application/ports/IResourceImporter.js`
 
-### IPropertyReconciler
-
+**IPropertyReconciler** - Fix property mismatches
 ```javascript
-/**
- * Port: Property Reconciler Interface
- *
- * Abstracts property reconciliation logic
- */
-class IPropertyReconciler {
-  /**
-   * Reconcile property mismatch
-   * @param {PropertyMismatch} mismatch
-   * @param {Resource} resource
-   * @returns {Promise<ReconciliationResult>}
-   */
-  async reconcile(mismatch, resource) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Plan reconciliation (dry run)
-   * @param {PropertyMismatch[]} mismatches
-   * @returns {Promise<ReconciliationPlan>}
-   */
-  async planReconciliation(mismatches) {
-    throw new Error('Not implemented');
-  }
-}
+// Example methods:
+async reconcile(mismatch, resource)
+async planReconciliation(mismatches)
 ```
+📄 See: `application/ports/IPropertyReconciler.js`
+
+> **Note**: Full interface definitions are maintained in source files. See the actual TypeScript/JSDoc definitions for complete method signatures and documentation.
 
 ---
 
 ## AWS Adapter Implementations
 
+AWS-specific implementations of the port interfaces using AWS SDK v3.
+
+**Source files**: `packages/devtools/infrastructure/domains/health/infrastructure/adapters/aws/`
+
 ### AWSStackRepository
 
-```javascript
-const { CloudFormationClient, DescribeStacksCommand, ListStackResourcesCommand } = require('@aws-sdk/client-cloudformation');
-const IStackRepository = require('../../application/ports/IStackRepository');
+Implements `IStackRepository` using CloudFormation API.
 
+```javascript
 class AWSStackRepository extends IStackRepository {
   constructor({ region }) {
-    super();
     this.client = new CloudFormationClient({ region });
   }
 
   async getStack(identifier) {
-    const command = new DescribeStacksCommand({
-      StackName: identifier.stackName,
-    });
-
-    try {
-      const response = await this.client.send(command);
-      return response.Stacks[0] || null;
-    } catch (error) {
-      if (error.name === 'ValidationError') {
-        return null; // Stack doesn't exist
-      }
-      throw error;
-    }
+    // Uses DescribeStacksCommand
+    // Returns Stack or null if not found
   }
 
   async listResources(identifier) {
-    const command = new ListStackResourcesCommand({
-      StackName: identifier.stackName,
-    });
-
-    const response = await this.client.send(command);
-
-    return response.StackResourceSummaries.map(resource => ({
-      logicalId: resource.LogicalResourceId,
-      physicalId: resource.PhysicalResourceId,
-      type: resource.ResourceType,
-      status: resource.ResourceStatus,
-      timestamp: resource.LastUpdatedTimestamp,
-    }));
-  }
-
-  async getOutputs(identifier) {
-    const stack = await this.getStack(identifier);
-    if (!stack) return {};
-
-    return (stack.Outputs || []).reduce((acc, output) => {
-      acc[output.OutputKey] = output.OutputValue;
-      return acc;
-    }, {});
-  }
-
-  async exists(identifier) {
-    return (await this.getStack(identifier)) !== null;
+    // Uses ListStackResourcesCommand
+    // Maps to standard resource format
   }
 }
-
-module.exports = AWSStackRepository;
 ```
 
+📄 See full implementation: `adapters/aws/AWSStackRepository.js`
+
 ### AWSResourceDetector
 
-```javascript
-const { EC2Client, DescribeVpcsCommand, DescribeSubnetsCommand } = require('@aws-sdk/client-ec2');
-const { RDSClient, DescribeDBClustersCommand } = require('@aws-sdk/client-rds');
-const { KMSClient, ListKeysCommand, DescribeKeyCommand } = require('@aws-sdk/client-kms');
-const IResourceDetector = require('../../application/ports/IResourceDetector');
+Implements `IResourceDetector` using AWS service APIs (EC2, RDS, KMS, etc.).
 
+```javascript
 class AWSResourceDetector extends IResourceDetector {
   constructor({ region }) {
-    super();
-    this.region = region;
     this.ec2 = new EC2Client({ region });
     this.rds = new RDSClient({ region });
     this.kms = new KMSClient({ region });
   }
 
   async detectNetworks(region) {
-    const command = new DescribeVpcsCommand({});
-    const response = await this.ec2.send(command);
-
-    return response.Vpcs.map(vpc => ({
-      type: 'AWS::EC2::VPC',
-      physicalId: vpc.VpcId,
-      properties: {
-        CidrBlock: vpc.CidrBlock,
-        Tags: vpc.Tags,
-        IsDefault: vpc.IsDefault,
-      },
-    }));
+    // Uses DescribeVpcsCommand
+    // Returns standardized network resources
   }
 
   async detectDatabases(region) {
-    const command = new DescribeDBClustersCommand({});
-    const response = await this.rds.send(command);
-
-    return response.DBClusters.map(cluster => ({
-      type: 'AWS::RDS::DBCluster',
-      physicalId: cluster.DBClusterIdentifier,
-      properties: {
-        Engine: cluster.Engine,
-        EngineVersion: cluster.EngineVersion,
-        DatabaseName: cluster.DatabaseName,
-        MasterUsername: cluster.MasterUsername,
-        Port: cluster.Port,
-      },
-    }));
+    // Uses DescribeDBClustersCommand
+    // Returns standardized database resources
   }
 
   async detectKeys(region) {
-    const listCommand = new ListKeysCommand({});
-    const response = await this.kms.send(listCommand);
-
-    const keys = [];
-    for (const key of response.Keys) {
-      const describeCommand = new DescribeKeyCommand({ KeyId: key.KeyId });
-      const keyDetails = await this.kms.send(describeCommand);
-
-      keys.push({
-        type: 'AWS::KMS::Key',
-        physicalId: keyDetails.KeyMetadata.KeyId,
-        properties: {
-          Description: keyDetails.KeyMetadata.Description,
-          Enabled: keyDetails.KeyMetadata.Enabled,
-          KeyUsage: keyDetails.KeyMetadata.KeyUsage,
-        },
-      });
-    }
-
-    return keys;
+    // Uses ListKeysCommand + DescribeKeyCommand
+    // Returns standardized key resources
   }
+}
+```
 
-  async detectResourceById(physicalId, resourceType) {
-    // Route to appropriate detector based on resource type
-    switch (resourceType) {
-      case 'AWS::EC2::VPC':
-        return this.detectVpcById(physicalId);
-      case 'AWS::RDS::DBCluster':
-        return this.detectClusterById(physicalId);
-      case 'AWS::KMS::Key':
-        return this.detectKeyById(physicalId);
-      default:
-        throw new Error(`Unsupported resource type: ${resourceType}`);
-    }
-  }
-
-  async getResourceProperties(physicalId, resourceType) {
-    const resource = await this.detectResourceById(physicalId, resourceType);
-    return resource ? resource.properties : null;
-  }
-
-  // Private helper methods
-  async detectVpcById(vpcId) {
-    const command = new DescribeVpcsCommand({ VpcIds: [vpcId] });
-    const response = await this.ec2.send(command);
-    const vpc = response.Vpcs[0];
-
-    if (!vpc) return null;
-
-    return {
-      type: 'AWS::EC2::VPC',
-      physicalId: vpc.VpcId,
-      properties: {
-        CidrBlock: vpc.CidrBlock,
-        Tags: vpc.Tags,
-        IsDefault: vpc.IsDefault,
-      },
-    };
-  }
+📄 See full implementation: `adapters/aws/AWSResourceDetector.js`
 
-  async detectClusterById(clusterId) {
-    const command = new DescribeDBClustersCommand({ DBClusterIdentifier: clusterId });
-    try {
-      const response = await this.rds.send(command);
-      const cluster = response.DBClusters[0];
-
-      return {
-        type: 'AWS::RDS::DBCluster',
-        physicalId: cluster.DBClusterIdentifier,
-        properties: {
-          Engine: cluster.Engine,
-          EngineVersion: cluster.EngineVersion,
-          DatabaseName: cluster.DatabaseName,
-          MasterUsername: cluster.MasterUsername,
-          Port: cluster.Port,
-        },
-      };
-    } catch (error) {
-      if (error.name === 'DBClusterNotFoundFault') {
-        return null;
-      }
-      throw error;
-    }
-  }
+### Other AWS Adapters
 
-  async detectKeyById(keyId) {
-    const command = new DescribeKeyCommand({ KeyId: keyId });
-    try {
-      const response = await this.kms.send(command);
-      return {
-        type: 'AWS::KMS::Key',
-        physicalId: response.KeyMetadata.KeyId,
-        properties: {
-          Description: response.KeyMetadata.Description,
-          Enabled: response.KeyMetadata.Enabled,
-          KeyUsage: response.KeyMetadata.KeyUsage,
-        },
-      };
-    } catch (error) {
-      if (error.name === 'NotFoundException') {
-        return null;
-      }
-      throw error;
-    }
-  }
-}
+- **AWSDriftDetector** - Uses CloudFormation drift detection API
+- **AWSResourceImporter** - Uses CloudFormation import change sets
+- **AWSPropertyReconciler** - Uses CloudFormation update stacks
 
-module.exports = AWSResourceDetector;
-```
+📄 See: `adapters/aws/` directory for all implementations
 
 ---