@friggframework/devtools 2.0.0-next.44 → 2.0.0-next.46

package/infrastructure/domains/integration/integration-resolver.js

@@ -0,0 +1,170 @@
+/**
+ * Integration Resource Resolver
+ *
+ * Domain Layer - Hexagonal Architecture
+ *
+ * Responsible for resolving ownership decisions for integration infrastructure:
+ * - SQS queues per integration
+ *
+ * Follows the ownership-based architecture pattern:
+ * - STACK: Create/manage resources in CloudFormation stack
+ * - EXTERNAL: Use existing resources by physical ID
+ * - AUTO: Intelligent decision based on discovery
+ */
+
+const BaseResourceResolver = require('../shared/base-resolver');
+const { ResourceOwnership } = require('../shared/types/resource-ownership');
+
+class IntegrationResourceResolver extends BaseResourceResolver {
+    /**
+     * Resolve ownership for all integration resources
+     * @param {Object} appDefinition - Application definition
+     * @param {Object} discovery - Structured discovery result
+     * @returns {Object} Ownership decisions for all integration resources
+     */
+    resolveAll(appDefinition, discovery) {
+        const integrations = appDefinition.integrations || [];
+        const decisions = {
+            // Shared resources used by all integrations
+            internalErrorQueue: this.resolveInternalErrorQueue(appDefinition, discovery),
+            // Per-integration queues
+            integrations: {},
+        };
+
+        // Resolve ownership for each integration's SQS queue
+        integrations.forEach(integration => {
+            const integrationName = integration.Definition?.name;
+            if (!integrationName) {
+                return; // Skip invalid integrations
+            }
+
+            decisions.integrations[integrationName] = {
+                queue: this.resolveQueue(integrationName, appDefinition, discovery),
+            };
+        });
+
+        return decisions;
+    }
+
+    /**
+     * Resolve ownership for the shared InternalErrorQueue (dead letter queue)
+     * @param {Object} appDefinition - Application definition
+     * @param {Object} discovery - Structured discovery result
+     * @returns {Object} Ownership decision for InternalErrorQueue
+     */
+    resolveInternalErrorQueue(appDefinition, discovery) {
+        const userIntent = appDefinition.integrations?.ownership?.internalErrorQueue || ResourceOwnership.AUTO;
+        const queueLogicalId = 'InternalErrorQueue';
+        const inStack = this.isInStack(queueLogicalId, discovery);
+
+        // STACK: User wants this in the CloudFormation stack
+        if (userIntent === ResourceOwnership.STACK) {
+            const stackResource = inStack ? this.findInStack(queueLogicalId, discovery) : null;
+            return this.createStackDecision(
+                stackResource?.physicalId || null,
+                inStack
+                    ? `Found ${queueLogicalId} in CloudFormation stack`
+                    : `Will create ${queueLogicalId} in stack`
+            );
+        }
+
+        // EXTERNAL: User wants to use an existing queue
+        if (userIntent === ResourceOwnership.EXTERNAL) {
+            const queueArn = appDefinition.integrations?.internalErrorQueue?.arn;
+            if (!queueArn) {
+                throw new Error(
+                    'InternalErrorQueue configured with ownership=external but integrations.internalErrorQueue.arn not provided'
+                );
+            }
+            return this.createExternalDecision(
+                queueArn,
+                `Using external InternalErrorQueue ARN: ${queueArn}`
+            );
+        }
+
+        // AUTO: Intelligent decision based on discovery
+        if (inStack) {
+            const stackResource = this.findInStack(queueLogicalId, discovery);
+            return this.createStackDecision(
+                stackResource.physicalId,
+                `Found ${queueLogicalId} in CloudFormation stack - will include definition (idempotent)`
+            );
+        }
+
+        // Default: Create in stack
+        return this.createStackDecision(
+            null,
+            `No existing ${queueLogicalId} found - will create in stack`
+        );
+    }
+
+    /**
+     * Resolve ownership for an integration's SQS queue
+     * @param {string} integrationName - Name of the integration (e.g., 'slack')
+     * @param {Object} appDefinition - Application definition
+     * @param {Object} discovery - Structured discovery result
+     * @returns {Object} Ownership decision for the queue
+     */
+    resolveQueue(integrationName, appDefinition, discovery) {
+        // Check for explicit ownership configuration
+        const integration = appDefinition.integrations?.find(
+            i => i.Definition?.name === integrationName
+        );
+        const userIntent = integration?.ownership?.queue || ResourceOwnership.AUTO;
+
+        // Queue logical ID follows pattern: ${IntegrationName}Queue (e.g., SlackQueue)
+        const queueLogicalId = `${this.capitalizeFirst(integrationName)}Queue`;
+        const inStack = this.isInStack(queueLogicalId, discovery);
+
+        // STACK: User wants this in the CloudFormation stack
+        if (userIntent === ResourceOwnership.STACK) {
+            const stackResource = inStack ? this.findInStack(queueLogicalId, discovery) : null;
+            return this.createStackDecision(
+                stackResource?.physicalId || null,
+                inStack
+                    ? `Found ${queueLogicalId} in CloudFormation stack`
+                    : `Will create ${queueLogicalId} in stack`
+            );
+        }
+
+        // EXTERNAL: User wants to use an existing queue
+        if (userIntent === ResourceOwnership.EXTERNAL) {
+            const queueUrl = integration?.queue?.url;
+            if (!queueUrl) {
+                throw new Error(
+                    `Integration '${integrationName}' configured with ownership=external but queue.url not provided`
+                );
+            }
+            return this.createExternalDecision(
+                queueUrl,
+                `Using external queue URL: ${queueUrl}`
+            );
+        }
+
+        // AUTO: Intelligent decision based on discovery
+        if (inStack) {
+            const stackResource = this.findInStack(queueLogicalId, discovery);
+            return this.createStackDecision(
+                stackResource.physicalId,
+                `Found ${queueLogicalId} in CloudFormation stack - will include definition (idempotent)`
+            );
+        }
+
+        // Default: Create in stack
+        return this.createStackDecision(
+            null,
+            `No existing ${queueLogicalId} found - will create in stack`
+        );
+    }
+
+    /**
+     * Capitalize first letter of string (e.g., 'slack' -> 'Slack')
+     * @param {string} str - String to capitalize
+     * @returns {string} Capitalized string
+     */
+    capitalizeFirst(str) {
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    }
+}
+
+module.exports = IntegrationResourceResolver;

package/infrastructure/domains/integration/integration-resolver.test.js

@@ -0,0 +1,369 @@
+/**
+ * Tests for IntegrationResourceResolver
+ */
+
+const IntegrationResourceResolver = require('./integration-resolver');
+const { ResourceOwnership } = require('../shared/types/resource-ownership');
+
+describe('IntegrationResourceResolver', () => {
+    let resolver;
+
+    beforeEach(() => {
+        resolver = new IntegrationResourceResolver();
+    });
+
+    describe('resolveAll', () => {
+        it('should resolve InternalErrorQueue and per-integration queues', () => {
+            const appDef = {
+                integrations: [
+                    { Definition: { name: 'slack' } },
+                    { Definition: { name: 'hubspot' } },
+                ],
+            };
+
+            const discovery = {
+                fromCloudFormationStack: false,
+                stackName: null,
+                existingLogicalIds: [],
+                stackManaged: [],
+                stackResources: {},
+                external: [],
+            };
+
+            const decisions = resolver.resolveAll(appDef, discovery);
+
+            expect(decisions.internalErrorQueue).toBeDefined();
+            expect(decisions.internalErrorQueue.ownership).toBe(ResourceOwnership.STACK);
+            expect(decisions.integrations.slack).toBeDefined();
+            expect(decisions.integrations.slack.queue.ownership).toBe(ResourceOwnership.STACK);
+            expect(decisions.integrations.hubspot).toBeDefined();
+            expect(decisions.integrations.hubspot.queue.ownership).toBe(ResourceOwnership.STACK);
+        });
+
+        it('should skip integrations without Definition.name', () => {
+            const appDef = {
+                integrations: [
+                    { Definition: { name: 'slack' } },
+                    { Definition: {} }, // Missing name
+                    { something: 'else' }, // Missing Definition
+                ],
+            };
+
+            const discovery = {
+                fromCloudFormationStack: false,
+                stackName: null,
+                existingLogicalIds: [],
+                stackManaged: [],
+                stackResources: {},
+                external: [],
+            };
+
+            const decisions = resolver.resolveAll(appDef, discovery);
+
+            expect(decisions.integrations.slack).toBeDefined();
+            expect(Object.keys(decisions.integrations)).toHaveLength(1);
+        });
+    });
+
+    describe('resolveInternalErrorQueue', () => {
+        it('should create in stack when nothing exists (AUTO)', () => {
+            const appDef = { integrations: [] };
+            const discovery = {
+                fromCloudFormationStack: false,
+                stackName: null,
+                existingLogicalIds: [],
+                stackManaged: [],
+                stackResources: {},
+                external: [],
+            };
+
+            const decision = resolver.resolveInternalErrorQueue(appDef, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.STACK);
+            expect(decision.physicalId).toBeNull();
+            expect(decision.reason).toContain('will create in stack');
+        });
+
+        it('should use stack resource when found (AUTO)', () => {
+            const appDef = { integrations: [] };
+            const discovery = {
+                fromCloudFormationStack: true,
+                stackName: 'test-stack',
+                existingLogicalIds: ['InternalErrorQueue'],
+                stackManaged: [
+                    {
+                        logicalId: 'InternalErrorQueue',
+                        physicalId: 'https://sqs.us-east-1.amazonaws.com/123456789/internal-error-queue',
+                        type: 'AWS::SQS::Queue',
+                    },
+                ],
+                stackResources: {
+                    InternalErrorQueue: {
+                        logicalId: 'InternalErrorQueue',
+                        physicalId: 'https://sqs.us-east-1.amazonaws.com/123456789/internal-error-queue',
+                        type: 'AWS::SQS::Queue',
+                    },
+                },
+                external: [],
+            };
+
+            const decision = resolver.resolveInternalErrorQueue(appDef, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.STACK);
+            expect(decision.physicalId).toBe('https://sqs.us-east-1.amazonaws.com/123456789/internal-error-queue');
+            expect(decision.reason).toContain('Found InternalErrorQueue in CloudFormation stack');
+        });
+
+        it('should respect explicit STACK ownership', () => {
+            const appDef = {
+                integrations: {
+                    ownership: {
+                        internalErrorQueue: ResourceOwnership.STACK,
+                    },
+                },
+            };
+            const discovery = {
+                fromCloudFormationStack: false,
+                stackName: null,
+                existingLogicalIds: [],
+                stackManaged: [],
+                stackResources: {},
+                external: [],
+            };
+
+            const decision = resolver.resolveInternalErrorQueue(appDef, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.STACK);
+            expect(decision.physicalId).toBeNull();
+        });
+
+        it('should use external ARN when ownership=EXTERNAL', () => {
+            const appDef = {
+                integrations: {
+                    ownership: {
+                        internalErrorQueue: ResourceOwnership.EXTERNAL,
+                    },
+                    internalErrorQueue: {
+                        arn: 'arn:aws:sqs:us-east-1:123456789:my-error-queue',
+                    },
+                },
+            };
+            const discovery = {
+                fromCloudFormationStack: false,
+                stackName: null,
+                existingLogicalIds: [],
+                stackManaged: [],
+                stackResources: {},
+                external: [],
+            };
+
+            const decision = resolver.resolveInternalErrorQueue(appDef, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+            expect(decision.physicalId).toBe('arn:aws:sqs:us-east-1:123456789:my-error-queue');
+            expect(decision.reason).toContain('Using external InternalErrorQueue ARN');
+        });
+
+        it('should throw when EXTERNAL ownership but no ARN provided', () => {
+            const appDef = {
+                integrations: {
+                    ownership: {
+                        internalErrorQueue: ResourceOwnership.EXTERNAL,
+                    },
+                },
+            };
+            const discovery = {
+                fromCloudFormationStack: false,
+                stackName: null,
+                existingLogicalIds: [],
+                stackManaged: [],
+                stackResources: {},
+                external: [],
+            };
+
+            expect(() => {
+                resolver.resolveInternalErrorQueue(appDef, discovery);
+            }).toThrow('InternalErrorQueue configured with ownership=external');
+        });
+    });
+
+    describe('resolveQueue', () => {
+        it('should create in stack when nothing exists (AUTO)', () => {
+            const appDef = {
+                integrations: [{ Definition: { name: 'slack' } }],
+            };
+            const discovery = {
+                fromCloudFormationStack: false,
+                stackName: null,
+                existingLogicalIds: [],
+                stackManaged: [],
+                stackResources: {},
+                external: [],
+            };
+
+            const decision = resolver.resolveQueue('slack', appDef, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.STACK);
+            expect(decision.physicalId).toBeNull();
+            expect(decision.reason).toContain('will create in stack');
+        });
+
+        it('should use stack resource when found (AUTO)', () => {
+            const appDef = {
+                integrations: [{ Definition: { name: 'slack' } }],
+            };
+            const discovery = {
+                fromCloudFormationStack: true,
+                stackName: 'test-stack',
+                existingLogicalIds: ['SlackQueue'],
+                stackManaged: [
+                    {
+                        logicalId: 'SlackQueue',
+                        physicalId: 'https://sqs.us-east-1.amazonaws.com/123456789/slack-queue',
+                        type: 'AWS::SQS::Queue',
+                    },
+                ],
+                stackResources: {
+                    SlackQueue: {
+                        logicalId: 'SlackQueue',
+                        physicalId: 'https://sqs.us-east-1.amazonaws.com/123456789/slack-queue',
+                        type: 'AWS::SQS::Queue',
+                    },
+                },
+                external: [],
+            };
+
+            const decision = resolver.resolveQueue('slack', appDef, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.STACK);
+            expect(decision.physicalId).toBe('https://sqs.us-east-1.amazonaws.com/123456789/slack-queue');
+            expect(decision.reason).toContain('Found SlackQueue in CloudFormation stack');
+        });
+
+        it('should respect per-integration STACK ownership', () => {
+            const appDef = {
+                integrations: [
+                    {
+                        Definition: { name: 'slack' },
+                        ownership: { queue: ResourceOwnership.STACK },
+                    },
+                ],
+            };
+            const discovery = {
+                fromCloudFormationStack: false,
+                stackName: null,
+                existingLogicalIds: [],
+                stackManaged: [],
+                stackResources: {},
+                external: [],
+            };
+
+            const decision = resolver.resolveQueue('slack', appDef, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.STACK);
+            expect(decision.physicalId).toBeNull();
+        });
+
+        it('should use external URL when ownership=EXTERNAL', () => {
+            const appDef = {
+                integrations: [
+                    {
+                        Definition: { name: 'slack' },
+                        ownership: { queue: ResourceOwnership.EXTERNAL },
+                        queue: { url: 'https://sqs.us-east-1.amazonaws.com/123456789/my-slack-queue' },
+                    },
+                ],
+            };
+            const discovery = {
+                fromCloudFormationStack: false,
+                stackName: null,
+                existingLogicalIds: [],
+                stackManaged: [],
+                stackResources: {},
+                external: [],
+            };
+
+            const decision = resolver.resolveQueue('slack', appDef, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+            expect(decision.physicalId).toBe('https://sqs.us-east-1.amazonaws.com/123456789/my-slack-queue');
+            expect(decision.reason).toContain('Using external queue URL');
+        });
+
+        it('should throw when EXTERNAL ownership but no URL provided', () => {
+            const appDef = {
+                integrations: [
+                    {
+                        Definition: { name: 'slack' },
+                        ownership: { queue: ResourceOwnership.EXTERNAL },
+                    },
+                ],
+            };
+            const discovery = {
+                fromCloudFormationStack: false,
+                stackName: null,
+                existingLogicalIds: [],
+                stackManaged: [],
+                stackResources: {},
+                external: [],
+            };
+
+            expect(() => {
+                resolver.resolveQueue('slack', appDef, discovery);
+            }).toThrow("Integration 'slack' configured with ownership=external but queue.url not provided");
+        });
+
+        it('should handle multiple integrations with different queues', () => {
+            const appDef = {
+                integrations: [
+                    { Definition: { name: 'slack' } },
+                    { Definition: { name: 'hubspot' } },
+                ],
+            };
+            const discovery = {
+                fromCloudFormationStack: true,
+                stackName: 'test-stack',
+                existingLogicalIds: ['SlackQueue'],
+                stackManaged: [
+                    {
+                        logicalId: 'SlackQueue',
+                        physicalId: 'https://sqs.us-east-1.amazonaws.com/123456789/slack-queue',
+                        type: 'AWS::SQS::Queue',
+                    },
+                ],
+                stackResources: {
+                    SlackQueue: {
+                        logicalId: 'SlackQueue',
+                        physicalId: 'https://sqs.us-east-1.amazonaws.com/123456789/slack-queue',
+                        type: 'AWS::SQS::Queue',
+                    },
+                },
+                external: [],
+            };
+
+            const slackDecision = resolver.resolveQueue('slack', appDef, discovery);
+            const hubspotDecision = resolver.resolveQueue('hubspot', appDef, discovery);
+
+            expect(slackDecision.ownership).toBe(ResourceOwnership.STACK);
+            expect(slackDecision.physicalId).toBe('https://sqs.us-east-1.amazonaws.com/123456789/slack-queue');
+            expect(hubspotDecision.ownership).toBe(ResourceOwnership.STACK);
+            expect(hubspotDecision.physicalId).toBeNull(); // HubspotQueue not in stack
+        });
+    });
+
+    describe('capitalizeFirst', () => {
+        it('should capitalize first letter', () => {
+            expect(resolver.capitalizeFirst('slack')).toBe('Slack');
+            expect(resolver.capitalizeFirst('hubspot')).toBe('Hubspot');
+            expect(resolver.capitalizeFirst('s')).toBe('S');
+        });
+
+        it('should handle already capitalized strings', () => {
+            expect(resolver.capitalizeFirst('Slack')).toBe('Slack');
+        });
+
+        it('should handle empty string', () => {
+            expect(resolver.capitalizeFirst('')).toBe('');
+        });
+    });
+});

package/infrastructure/domains/integration/websocket-builder.js

@@ -0,0 +1,69 @@
+/**
+ * WebSocket Builder
+ * 
+ * Domain Layer - Hexagonal Architecture
+ * 
+ * Responsible for:
+ * - WebSocket API Gateway configuration
+ * - WebSocket route handlers ($connect, $default, $disconnect)
+ * - WebSocket function definitions
+ */
+
+const { InfrastructureBuilder, ValidationResult } = require('../shared/base-builder');
+
+class WebsocketBuilder extends InfrastructureBuilder {
+    constructor() {
+        super();
+        this.name = 'WebsocketBuilder';
+    }
+
+    shouldExecute(appDefinition) {
+        // Skip WebSocket in local mode (when FRIGG_SKIP_AWS_DISCOVERY is set)
+        // API Gateway WebSocket is an AWS-specific service that should only be created in production
+        if (process.env.FRIGG_SKIP_AWS_DISCOVERY === 'true') {
+            return false;
+        }
+
+        return appDefinition.websockets?.enable === true;
+    }
+
+    validate(appDefinition) {
+        const result = new ValidationResult();
+
+        if (!appDefinition.websockets) {
+            result.addError('WebSocket configuration is missing');
+            return result;
+        }
+
+        return result;
+    }
+
+    /**
+     * Build WebSocket infrastructure
+     */
+    async build(appDefinition, discoveredResources) {
+        console.log(`\n[${this.name}] Configuring WebSocket API Gateway...`);
+
+        const result = {
+            functions: {},
+        };
+
+        // Create default WebSocket handler
+        result.functions.defaultWebsocket = {
+            handler: 'node_modules/@friggframework/core/handlers/routers/websocket.handler',
+            events: [
+                { websocket: { route: '$connect' } },
+                { websocket: { route: '$default' } },
+                { websocket: { route: '$disconnect' } },
+            ],
+        };
+
+        console.log('  ✅ WebSocket functions configured ($connect, $default, $disconnect)');
+        console.log(`[${this.name}] ✅ WebSocket configuration completed`);
+
+        return result;
+    }
+}
+
+module.exports = { WebsocketBuilder };
+