@friggframework/devtools 2.0.0--canary.461.ec909cf.0 → 2.0.0--canary.461.9483dbe.0

package/infrastructure/domains/shared/base-builder.js

@@ -0,0 +1,112 @@
+/**
+ * Base Infrastructure Builder Interface
+ * 
+ * Domain Layer - Hexagonal Architecture
+ * 
+ * This abstract class defines the contract for all infrastructure builders.
+ * Each infrastructure domain (VPC, KMS, Database, etc.) implements this interface.
+ * 
+ * Benefits of Hexagonal Architecture:
+ * - Domain logic separated from infrastructure concerns
+ * - Easy to test in isolation
+ * - Dependency injection for cross-cutting concerns
+ * - Clear boundaries between domains
+ * - Enables parallel execution where dependencies allow
+ */
+
+class InfrastructureBuilder {
+    /**
+     * Build infrastructure resources
+     * 
+     * @param {Object} appDefinition - Application definition from user
+     * @param {Object} discoveredResources - Resources discovered from AWS
+     * @returns {Object} CloudFormation resources to add to template
+     * @throws {Error} If validation fails or build encounters errors
+     */
+    async build(appDefinition, discoveredResources) {
+        throw new Error('InfrastructureBuilder.build() must be implemented by subclass');
+    }
+
+    /**
+     * Validate configuration before building
+     * 
+     * @param {Object} config - Configuration to validate
+     * @returns {Object} Validation result { valid: boolean, errors: string[] }
+     */
+    validate(config) {
+        throw new Error('InfrastructureBuilder.validate() must be implemented by subclass');
+    }
+
+    /**
+     * Check if this builder should execute
+     * 
+     * @param {Object} appDefinition - Application definition
+     * @returns {boolean} True if builder should execute
+     */
+    shouldExecute(appDefinition) {
+        return false;
+    }
+
+    /**
+     * Get dependencies (other builders that must execute first)
+     * 
+     * @returns {Array<string>} Array of builder names this depends on
+     */
+    getDependencies() {
+        return [];
+    }
+
+    /**
+     * Get builder name for logging and dependency resolution
+     * 
+     * @returns {string} Builder name
+     */
+    getName() {
+        return this.constructor.name;
+    }
+}
+
+/**
+ * Value Object for validation results
+ */
+class ValidationResult {
+    constructor(valid = true, errors = [], warnings = []) {
+        this.valid = valid;
+        this.errors = errors;
+        this.warnings = warnings;
+    }
+
+    addError(error) {
+        this.errors.push(error);
+        this.valid = false;
+    }
+
+    addWarning(warning) {
+        this.warnings.push(warning);
+    }
+
+    hasErrors() {
+        return this.errors.length > 0;
+    }
+
+    hasWarnings() {
+        return this.warnings.length > 0;
+    }
+
+    toString() {
+        let result = `Valid: ${this.valid}\n`;
+        if (this.errors.length > 0) {
+            result += `Errors:\n  - ${this.errors.join('\n  - ')}\n`;
+        }
+        if (this.warnings.length > 0) {
+            result += `Warnings:\n  - ${this.warnings.join('\n  - ')}\n`;
+        }
+        return result;
+    }
+}
+
+module.exports = {
+    InfrastructureBuilder,
+    ValidationResult,
+};
+

package/infrastructure/domains/shared/builder-orchestrator.js

@@ -0,0 +1,212 @@
+/**
+ * Infrastructure Builder Orchestrator
+ * 
+ * Application Layer - Hexagonal Architecture
+ * 
+ * Orchestrates the execution of all infrastructure builders with:
+ * - Dependency resolution
+ * - Parallel execution where possible
+ * - Error handling and validation
+ * - Progress reporting
+ */
+
+const { gatherDiscoveredResources } = require('./resource-discovery');
+const { getAppEnvironmentVars, buildEnvironment } = require('./environment-builder');
+
+class BuilderOrchestrator {
+    constructor(builders = []) {
+        this.builders = new Map();
+        builders.forEach(builder => this.registerBuilder(builder));
+    }
+
+    /**
+     * Register a builder
+     */
+    registerBuilder(builder) {
+        this.builders.set(builder.getName(), builder);
+    }
+
+    /**
+     * Validate all applicable builders
+     */
+    async validateAll(appDefinition) {
+        console.log('\n🔍 Validating infrastructure configuration...');
+
+        const validationResults = [];
+        let hasErrors = false;
+
+        for (const [name, builder] of this.builders) {
+            if (builder.shouldExecute(appDefinition)) {
+                const result = builder.validate(appDefinition);
+                validationResults.push({ builder: name, result });
+
+                if (result.hasErrors()) {
+                    hasErrors = true;
+                    console.log(`❌ ${name} validation failed:`);
+                    result.errors.forEach(error => console.log(`   - ${error}`));
+                }
+
+                if (result.hasWarnings()) {
+                    console.log(`⚠️  ${name} warnings:`);
+                    result.warnings.forEach(warning => console.log(`   - ${warning}`));
+                }
+            }
+        }
+
+        if (hasErrors) {
+            throw new Error('Infrastructure validation failed. See errors above.');
+        }
+
+        console.log('✅ All infrastructure validation passed\n');
+        return validationResults;
+    }
+
+    /**
+     * Resolve builder execution order based on dependencies
+     */
+    resolveBuildOrder(appDefinition) {
+        const executionOrder = [];
+        const visited = new Set();
+        const visiting = new Set();
+
+        const visit = (builderName) => {
+            if (visited.has(builderName)) return;
+            if (visiting.has(builderName)) {
+                throw new Error(`Circular dependency detected: ${builderName}`);
+            }
+
+            const builder = this.builders.get(builderName);
+            if (!builder || !builder.shouldExecute(appDefinition)) {
+                return;
+            }
+
+            visiting.add(builderName);
+
+            // Visit dependencies first
+            const dependencies = builder.getDependencies() || [];
+            dependencies.forEach(dep => visit(dep));
+
+            visiting.delete(builderName);
+            visited.add(builderName);
+            executionOrder.push(builderName);
+        };
+
+        // Visit all builders
+        for (const [builderName] of this.builders) {
+            visit(builderName);
+        }
+
+        return executionOrder;
+    }
+
+    /**
+     * Build all infrastructure
+     */
+    async buildAll(appDefinition) {
+        console.log('\n🏗️  Building infrastructure...');
+
+        // Step 1: Validate configuration
+        await this.validateAll(appDefinition);
+
+        // Step 2: Discover AWS resources
+        const discoveredResources = await gatherDiscoveredResources(appDefinition);
+
+        // Step 3: Resolve build order
+        const buildOrder = this.resolveBuildOrder(appDefinition);
+        console.log(`📋 Build order: ${buildOrder.join(' → ')}\n`);
+
+        // Step 4: Execute builders in order
+        const buildResults = {};
+
+        for (const builderName of buildOrder) {
+            const builder = this.builders.get(builderName);
+            try {
+                const result = await builder.build(appDefinition, discoveredResources);
+                buildResults[builderName] = result;
+            } catch (error) {
+                console.error(`❌ ${builderName} build failed:`, error.message);
+                throw error;
+            }
+        }
+
+        // Step 5: Merge results
+        return this.mergeResults(buildResults, appDefinition, discoveredResources);
+    }
+
+    /**
+     * Merge builder results into cohesive definition
+     */
+    mergeResults(buildResults, appDefinition, discoveredResources) {
+        console.log('\n🔗 Merging infrastructure results...');
+
+        const merged = {
+            resources: {},
+            iamStatements: [],
+            environment: {},
+            functions: {},
+            layers: {},
+            plugins: [],
+            custom: {},
+            vpcConfig: null,
+        };
+
+        // Merge results from each builder
+        for (const [builderName, result] of Object.entries(buildResults)) {
+            // Merge resources
+            if (result.resources) {
+                Object.assign(merged.resources, result.resources);
+            }
+
+            // Merge IAM statements
+            if (result.iamStatements) {
+                merged.iamStatements.push(...result.iamStatements);
+            }
+
+            // Merge environment variables
+            if (result.environment) {
+                Object.assign(merged.environment, result.environment);
+            }
+
+            // Merge functions
+            if (result.functions) {
+                Object.assign(merged.functions, result.functions);
+            }
+
+            // Merge layers
+            if (result.layers) {
+                Object.assign(merged.layers, result.layers);
+            }
+
+            // Merge plugins
+            if (result.plugins) {
+                merged.plugins.push(...result.plugins);
+            }
+
+            // Merge custom configuration
+            if (result.pluginConfig) {
+                Object.assign(merged.custom, result.pluginConfig);
+            }
+            if (result.custom) {
+                Object.assign(merged.custom, result.custom);
+            }
+
+            // Capture VPC config (from VpcBuilder)
+            if (result.vpcConfig) {
+                merged.vpcConfig = result.vpcConfig;
+            }
+
+            console.log(`  ✓ Merged ${builderName} results`);
+        }
+
+        console.log('✅ Infrastructure build completed successfully\n');
+
+        return {
+            merged,
+            discoveredResources,
+            appEnvironmentVars: getAppEnvironmentVars(appDefinition),
+        };
+    }
+}
+
+module.exports = { BuilderOrchestrator };
+

package/infrastructure/domains/shared/builder-orchestrator.test.js

@@ -0,0 +1,213 @@
+/**
+ * Tests for BuilderOrchestrator
+ * 
+ * Tests orchestration, dependency resolution, and parallel execution
+ */
+
+const { BuilderOrchestrator } = require('./builder-orchestrator');
+const { InfrastructureBuilder, ValidationResult } = require('./base-builder');
+
+// Mock builders for testing
+class MockBuilderA extends InfrastructureBuilder {
+    getName() { return 'MockBuilderA'; }
+    shouldExecute(appDef) { return appDef.featureA === true; }
+    validate(appDef) { return new ValidationResult(); }
+    async build(appDef, discovered) {
+        return {
+            resources: { ResourceA: { Type: 'Test' } },
+            iamStatements: [{ Effect: 'Allow', Action: 'test:A' }],
+        };
+    }
+}
+
+class MockBuilderB extends InfrastructureBuilder {
+    getName() { return 'MockBuilderB'; }
+    shouldExecute(appDef) { return appDef.featureB === true; }
+    validate(appDef) { return new ValidationResult(); }
+    getDependencies() { return ['MockBuilderA']; }  // Depends on A
+    async build(appDef, discovered) {
+        return {
+            resources: { ResourceB: { Type: 'Test' } },
+            environment: { VAR_B: 'value-b' },
+        };
+    }
+}
+
+class MockBuilderC extends InfrastructureBuilder {
+    getName() { return 'MockBuilderC'; }
+    shouldExecute() { return false; }  // Never executes
+    validate() { return new ValidationResult(); }
+    async build() {
+        throw new Error('Should not be called');
+    }
+}
+
+jest.mock('./resource-discovery', () => ({
+    gatherDiscoveredResources: jest.fn().mockResolvedValue({ discovered: true }),
+}));
+
+jest.mock('./environment-builder', () => ({
+    getAppEnvironmentVars: jest.fn().mockReturnValue({ ENV_VAR: 'value' }),
+    buildEnvironment: jest.fn().mockReturnValue({ ENV_VAR: 'value' }),
+}));
+
+describe('BuilderOrchestrator', () => {
+    let orchestrator;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    describe('registerBuilder()', () => {
+        it('should register builders', () => {
+            orchestrator = new BuilderOrchestrator();
+            const builder = new MockBuilderA();
+
+            orchestrator.registerBuilder(builder);
+
+            expect(orchestrator.builders.has('MockBuilderA')).toBe(true);
+        });
+
+        it('should register multiple builders via constructor', () => {
+            orchestrator = new BuilderOrchestrator([
+                new MockBuilderA(),
+                new MockBuilderB(),
+            ]);
+
+            expect(orchestrator.builders.size).toBe(2);
+        });
+    });
+
+    describe('validateAll()', () => {
+        it('should validate all applicable builders', async () => {
+            orchestrator = new BuilderOrchestrator([
+                new MockBuilderA(),
+                new MockBuilderB(),
+            ]);
+
+            const appDef = { featureA: true, featureB: true };
+
+            await expect(orchestrator.validateAll(appDef)).resolves.toBeDefined();
+        });
+
+        it('should skip builders that shouldNotExecute', async () => {
+            orchestrator = new BuilderOrchestrator([
+                new MockBuilderA(),
+                new MockBuilderC(),  // Should not execute
+            ]);
+
+            const appDef = { featureA: true };
+
+            const results = await orchestrator.validateAll(appDef);
+
+            // Should only validate MockBuilderA
+            expect(results).toHaveLength(1);
+            expect(results[0].builder).toBe('MockBuilderA');
+        });
+
+        it('should throw error if validation fails', async () => {
+            class FailingBuilder extends InfrastructureBuilder {
+                getName() { return 'FailingBuilder'; }
+                shouldExecute() { return true; }
+                validate() {
+                    const result = new ValidationResult();
+                    result.addError('Test error');
+                    return result;
+                }
+            }
+
+            orchestrator = new BuilderOrchestrator([new FailingBuilder()]);
+
+            await expect(orchestrator.validateAll({})).rejects.toThrow('Infrastructure validation failed');
+        });
+    });
+
+    describe('resolveBuildOrder()', () => {
+        it('should resolve dependencies correctly', () => {
+            orchestrator = new BuilderOrchestrator([
+                new MockBuilderB(),  // Depends on A
+                new MockBuilderA(),  // No dependencies
+            ]);
+
+            const appDef = { featureA: true, featureB: true };
+            const order = orchestrator.resolveBuildOrder(appDef);
+
+            // A should come before B
+            expect(order).toEqual(['MockBuilderA', 'MockBuilderB']);
+        });
+
+        it('should handle builders with no dependencies', () => {
+            orchestrator = new BuilderOrchestrator([
+                new MockBuilderA(),
+            ]);
+
+            const appDef = { featureA: true };
+            const order = orchestrator.resolveBuildOrder(appDef);
+
+            expect(order).toEqual(['MockBuilderA']);
+        });
+
+        it('should skip builders that should not execute', () => {
+            orchestrator = new BuilderOrchestrator([
+                new MockBuilderA(),
+                new MockBuilderC(),  // Should not execute
+            ]);
+
+            const appDef = { featureA: true };
+            const order = orchestrator.resolveBuildOrder(appDef);
+
+            expect(order).toEqual(['MockBuilderA']);
+        });
+    });
+
+    describe('buildAll()', () => {
+        it('should build all infrastructure and merge results', async () => {
+            orchestrator = new BuilderOrchestrator([
+                new MockBuilderA(),
+                new MockBuilderB(),
+            ]);
+
+            const appDef = { featureA: true, featureB: true };
+
+            const result = await orchestrator.buildAll(appDef);
+
+            expect(result.merged).toBeDefined();
+            expect(result.merged.resources).toMatchObject({
+                ResourceA: { Type: 'Test' },
+                ResourceB: { Type: 'Test' },
+            });
+            expect(result.merged.iamStatements).toHaveLength(1);
+            expect(result.merged.environment).toMatchObject({ VAR_B: 'value-b' });
+        });
+
+        it('should skip builders that should not execute', async () => {
+            orchestrator = new BuilderOrchestrator([
+                new MockBuilderA(),
+                new MockBuilderC(),  // Should not execute
+            ]);
+
+            const appDef = { featureA: true };
+
+            const result = await orchestrator.buildAll(appDef);
+
+            // Should only have results from A
+            expect(Object.keys(result.merged.resources)).toEqual(['ResourceA']);
+        });
+
+        it('should throw error if builder fails', async () => {
+            class FailingBuilder extends InfrastructureBuilder {
+                getName() { return 'FailingBuilder'; }
+                shouldExecute() { return true; }
+                validate() { return new ValidationResult(); }
+                async build() {
+                    throw new Error('Build failed');
+                }
+            }
+
+            orchestrator = new BuilderOrchestrator([new FailingBuilder()]);
+
+            await expect(orchestrator.buildAll({})).rejects.toThrow('Build failed');
+        });
+    });
+});
+

package/infrastructure/domains/shared/environment-builder.js

@@ -0,0 +1,118 @@
+/**
+ * Environment Builder Service
+ * 
+ * Domain Service - Hexagonal Architecture
+ * 
+ * Builds Lambda environment variable configuration from:
+ * 1. AppDefinition environment flags
+ * 2. Discovered AWS resources (VPC IDs, KMS keys, etc.)
+ * 3. Generated resource references
+ */
+
+/**
+ * Get environment variables from AppDefinition
+ * 
+ * Extracts environment variable definitions where value is true,
+ * and creates Serverless variable references.
+ * 
+ * @param {Object} appDefinition - Application definition
+ * @returns {Object} Environment variable mappings
+ */
+function getAppEnvironmentVars(appDefinition) {
+    const envVars = {};
+    const reservedVars = new Set([
+        '_HANDLER',
+        '_X_AMZN_TRACE_ID',
+        'AWS_DEFAULT_REGION',
+        'AWS_EXECUTION_ENV',
+        'AWS_REGION',
+        'AWS_LAMBDA_FUNCTION_NAME',
+        'AWS_LAMBDA_FUNCTION_MEMORY_SIZE',
+        'AWS_LAMBDA_FUNCTION_VERSION',
+        'AWS_LAMBDA_INITIALIZATION_TYPE',
+        'AWS_LAMBDA_LOG_GROUP_NAME',
+        'AWS_LAMBDA_LOG_STREAM_NAME',
+        'AWS_ACCESS_KEY',
+        'AWS_ACCESS_KEY_ID',
+        'AWS_SECRET_ACCESS_KEY',
+        'AWS_SESSION_TOKEN',
+    ]);
+
+    if (!appDefinition.environment) {
+        return envVars;
+    }
+
+    console.log('📋 Loading environment variables from appDefinition...');
+    const envKeys = [];
+    const skippedKeys = [];
+
+    for (const [key, value] of Object.entries(appDefinition.environment)) {
+        if (value !== true) continue;
+        if (reservedVars.has(key)) {
+            skippedKeys.push(key);
+            continue;
+        }
+        envVars[key] = `\${env:${key}, ''}`;
+        envKeys.push(key);
+    }
+
+    if (envKeys.length > 0) {
+        console.log(
+            `   Found ${envKeys.length} environment variables: ${envKeys.join(
+                ', '
+            )}`
+        );
+    }
+    if (skippedKeys.length > 0) {
+        console.log(
+            `   ⚠️  Skipped ${skippedKeys.length
+            } reserved AWS Lambda variables: ${skippedKeys.join(', ')}`
+        );
+    }
+
+    return envVars;
+}
+
+/**
+ * Build complete environment configuration for Lambda functions
+ * 
+ * Combines app environment vars with discovered AWS resource references
+ * 
+ * @param {Object} appEnvironmentVars - Environment vars from AppDefinition
+ * @param {Object} discoveredResources - Discovered AWS resources
+ * @returns {Object} Complete environment configuration
+ */
+function buildEnvironment(appEnvironmentVars, discoveredResources) {
+    const environment = {
+        ...appEnvironmentVars,
+        FRIGG_STACK: '${self:service}',
+        FRIGG_STAGE: '${self:provider.stage}',
+        FRIGG_REGION: '${self:provider.region}',
+    };
+
+    // Add KMS key if discovered or created
+    if (discoveredResources.kmsKeyId) {
+        environment.KMS_KEY_ARN = discoveredResources.kmsKeyId;
+    } else if (discoveredResources.kmsKeyArn) {
+        environment.KMS_KEY_ARN = discoveredResources.kmsKeyArn;
+    }
+
+    // Add database connection info if discovered
+    if (discoveredResources.auroraClusterEndpoint) {
+        environment.DATABASE_HOST = discoveredResources.auroraClusterEndpoint;
+        environment.DATABASE_PORT = String(discoveredResources.auroraPort || 5432);
+    }
+
+    // Add secrets manager secret ARN if discovered
+    if (discoveredResources.databaseSecretArn) {
+        environment.DATABASE_SECRET_ARN = discoveredResources.databaseSecretArn;
+    }
+
+    return environment;
+}
+
+module.exports = {
+    getAppEnvironmentVars,
+    buildEnvironment,
+};
+