@friggframework/devtools 2.0.0-next.10 → 2.0.0-next.101

package/infrastructure/domains/shared/types/app-definition.js

@@ -0,0 +1,225 @@
+/**
+ * @fileoverview App definition types
+ *
+ * Defines the structure of the application definition with new ownership-based schema.
+ * This replaces the old 'management' mode system.
+ */
+
+/**
+ * VPC configuration
+ * @typedef {Object} VpcDefinition
+ * @property {boolean} enable - Whether VPC is enabled
+ *
+ * @property {Object} [ownership] - Resource ownership configuration
+ * @property {'stack'|'external'|'auto'} [ownership.vpc] - VPC ownership
+ * @property {'stack'|'external'|'auto'} [ownership.securityGroup] - Security group ownership
+ * @property {'stack'|'external'|'auto'} [ownership.subnets] - Subnets ownership
+ * @property {'stack'|'external'|'auto'} [ownership.natGateway] - NAT gateway ownership
+ * @property {'stack'|'external'|'auto'} [ownership.vpcEndpoints] - VPC endpoints ownership
+ *
+ * @property {Object} [external] - External resource references (required if ownership='external')
+ * @property {string} [external.vpcId] - External VPC ID
+ * @property {string[]} [external.securityGroupIds] - External security group IDs
+ * @property {string[]} [external.subnetIds] - External subnet IDs
+ * @property {string} [external.natGatewayId] - External NAT gateway ID
+ * @property {Object} [external.vpcEndpointIds] - External VPC endpoint IDs
+ * @property {string} [external.vpcEndpointIds.s3] - S3 endpoint ID
+ * @property {string} [external.vpcEndpointIds.dynamodb] - DynamoDB endpoint ID
+ * @property {string} [external.vpcEndpointIds.kms] - KMS endpoint ID
+ * @property {string} [external.vpcEndpointIds.secretsManager] - Secrets Manager endpoint ID
+ * @property {string} [external.vpcEndpointIds.sqs] - SQS endpoint ID
+ *
+ * @property {Object} [config] - Configuration preferences
+ * @property {boolean} [config.selfHeal] - Auto-configure NAT/routes/etc (default: false)
+ * @property {string} [config.cidrBlock] - CIDR block for stack-owned VPC (default: '10.0.0.0/16')
+ * @property {boolean} [config.enableVpcEndpoints] - Enable VPC endpoints (default: true)
+ * @property {Object} [config.natGateway] - NAT Gateway configuration
+ * @property {boolean} [config.natGateway.enable] - Enable NAT Gateway (default: true)
+ */
+
+/**
+ * Aurora PostgreSQL configuration
+ * @typedef {Object} AuroraDefinition
+ * @property {boolean} enable - Whether Aurora is enabled
+ *
+ * @property {Object} [ownership] - Resource ownership configuration
+ * @property {'stack'|'external'|'auto'} [ownership.cluster] - Aurora cluster ownership
+ * @property {'stack'|'external'|'auto'} [ownership.subnetGroup] - DB subnet group ownership
+ * @property {'stack'|'external'|'auto'} [ownership.secret] - Secrets Manager secret ownership
+ *
+ * @property {Object} [external] - External resource references
+ * @property {string} [external.clusterId] - External cluster identifier
+ * @property {string} [external.clusterEndpoint] - External cluster endpoint
+ * @property {number} [external.port] - External cluster port
+ * @property {string} [external.secretArn] - External Secrets Manager ARN
+ *
+ * @property {Object} [config] - Configuration preferences
+ * @property {'aurora-postgresql'|'aurora-mysql'} [config.engine] - Database engine
+ * @property {number} [config.minCapacity] - Min serverless capacity (default: 0.5)
+ * @property {number} [config.maxCapacity] - Max serverless capacity (default: 1)
+ * @property {string} [config.database] - Database name (default: 'frigg')
+ * @property {boolean} [config.publiclyAccessible] - Public access (default: false)
+ * @property {boolean} [config.autoCreateCredentials] - Auto-create credentials in Secrets Manager
+ */
+
+/**
+ * KMS encryption configuration
+ * @typedef {Object} KmsDefinition
+ * @property {boolean} enable - Whether KMS is enabled
+ *
+ * @property {Object} [ownership] - Resource ownership configuration
+ * @property {'stack'|'external'|'auto'} [ownership.key] - KMS key ownership
+ *
+ * @property {Object} [external] - External resource references
+ * @property {string} [external.keyId] - External KMS key ID or ARN
+ * @property {string} [external.keyAlias] - External KMS key alias
+ *
+ * @property {Object} [config] - Configuration preferences
+ * @property {boolean} [config.enableKeyRotation] - Enable automatic key rotation
+ * @property {string} [config.description] - Key description
+ */
+
+/**
+ * SSM Parameter Store configuration
+ * @typedef {Object} SsmDefinition
+ * @property {boolean} enable - Whether SSM is enabled
+ * @property {string[]} [parameterPaths] - Parameter paths to grant access to
+ */
+
+/**
+ * Database migration configuration
+ * @typedef {Object} MigrationDefinition
+ * @property {boolean} enable - Whether migrations are enabled
+ * @property {string} [migrationPath] - Path to migration files
+ */
+
+/**
+ * WebSocket configuration
+ * @typedef {Object} WebsocketDefinition
+ * @property {boolean} enable - Whether WebSocket API is enabled
+ */
+
+/**
+ * Integration configuration
+ * @typedef {Object} IntegrationDefinition
+ * @property {Object} Definition - Integration definition object
+ * @property {string} Definition.name - Integration name
+ */
+
+/**
+ * Admin script definition
+ * @typedef {Object} AdminScriptDefinition
+ * @property {Object} Definition - Static definition from script class
+ * @property {string} Definition.name - Script name identifier
+ * @property {string} Definition.version - Script version (semver)
+ * @property {string} [Definition.description] - Human-readable description
+ * @property {Object} [Definition.schedule] - Schedule configuration
+ * @property {boolean} [Definition.schedule.enabled] - Whether scheduling is enabled
+ * @property {string} [Definition.schedule.cronExpression] - Cron expression
+ */
+
+/**
+ * Admin configuration
+ * @typedef {Object} AdminConfig
+ * @property {boolean} [enableScheduling] - Whether to enable EventBridge scheduling
+ */
+
+/**
+ * Complete application definition
+ * @typedef {Object} AppDefinition
+ * @property {string} name - Application name
+ * @property {string} stage - Deployment stage (e.g., 'dev', 'production')
+ * @property {string} provider - Cloud provider (e.g., 'aws')
+ * @property {string} region - AWS region
+ *
+ * @property {VpcDefinition} [vpc] - VPC configuration
+ * @property {Object} [database] - Database configuration
+ * @property {AuroraDefinition} [database.postgres] - PostgreSQL configuration
+ * @property {KmsDefinition} [encryption] - KMS encryption configuration
+ * @property {SsmDefinition} [ssm] - SSM Parameter Store configuration
+ * @property {MigrationDefinition} [migrations] - Database migration configuration
+ * @property {WebsocketDefinition} [websockets] - WebSocket API configuration
+ * @property {IntegrationDefinition[]} [integrations] - Integration definitions
+ * @property {AdminScriptDefinition[]} [adminScripts] - Admin script definitions
+ * @property {AdminConfig} [admin] - Admin configuration
+ *
+ * @property {Object} [environment] - Environment variables
+ */
+
+/**
+ * Validate app definition has required fields
+ * @param {AppDefinition} appDefinition - App definition to validate
+ * @throws {Error} If required fields are missing
+ */
+function validateAppDefinition(appDefinition) {
+    if (!appDefinition) {
+        throw new Error('App definition is required');
+    }
+
+    if (!appDefinition.name) {
+        throw new Error('App definition must have a name');
+    }
+
+    if (!appDefinition.provider) {
+        throw new Error('App definition must have a provider');
+    }
+
+    if (!appDefinition.region) {
+        throw new Error('App definition must have a region');
+    }
+}
+
+/**
+ * Get stack name from app definition
+ * @param {AppDefinition} appDefinition - App definition
+ * @returns {string} Stack name
+ */
+function getStackName(appDefinition) {
+    const stage = appDefinition.stage || 'dev';
+    return `${appDefinition.name}-${stage}`;
+}
+
+/**
+ * Check if VPC is enabled
+ * @param {AppDefinition} appDefinition - App definition
+ * @returns {boolean}
+ */
+function isVpcEnabled(appDefinition) {
+    return appDefinition.vpc?.enable === true;
+}
+
+/**
+ * Check if Aurora is enabled
+ * @param {AppDefinition} appDefinition - App definition
+ * @returns {boolean}
+ */
+function isAuroraEnabled(appDefinition) {
+    return appDefinition.database?.postgres?.enable === true;
+}
+
+/**
+ * Check if KMS is enabled
+ * @param {AppDefinition} appDefinition - App definition
+ * @returns {boolean}
+ */
+function isKmsEnabled(appDefinition) {
+    return appDefinition.encryption?.enable === true;
+}
+
+/**
+ * Check if SSM is enabled
+ * @param {AppDefinition} appDefinition - App definition
+ * @returns {boolean}
+ */
+function isSsmEnabled(appDefinition) {
+    return appDefinition.ssm?.enable === true;
+}
+
+module.exports = {
+    validateAppDefinition,
+    getStackName,
+    isVpcEnabled,
+    isAuroraEnabled,
+    isKmsEnabled,
+    isSsmEnabled
+};

package/infrastructure/domains/shared/types/discovery-result.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Discovery result types
+ *
+ * Defines the structure of resource discovery results.
+ * Discovery reports FACTS - it doesn't make ownership decisions.
+ */
+
+/**
+ * Resource that exists in our CloudFormation stack
+ * @typedef {Object} StackManagedResource
+ * @property {string} logicalId - CloudFormation logical resource ID (e.g., 'FriggLambdaSecurityGroup')
+ * @property {string} physicalId - AWS physical resource ID (e.g., 'sg-069629001ade41c9a')
+ * @property {string} resourceType - CloudFormation resource type (e.g., 'AWS::EC2::SecurityGroup')
+ * @property {Object} [properties] - Resource properties (optional, for detailed info)
+ */
+
+/**
+ * Resource that exists outside our CloudFormation stack
+ * @typedef {Object} ExternalResource
+ * @property {string} physicalId - AWS physical resource ID
+ * @property {string} resourceType - CloudFormation resource type
+ * @property {'tag-search' | 'name-search' | 'aws-api' | 'user-provided'} source - How it was discovered
+ * @property {Object} [properties] - Resource properties (optional)
+ * @property {Object} [tags] - Resource tags (if available)
+ */
+
+/**
+ * Complete discovery result
+ * @typedef {Object} DiscoveryResult
+ * @property {StackManagedResource[]} stackManaged - Resources in OUR CloudFormation stack
+ * @property {ExternalResource[]} external - Resources outside our stack
+ * @property {string} [stackName] - Name of our CloudFormation stack (if exists)
+ * @property {boolean} fromCloudFormation - Whether stack was found in CloudFormation
+ * @property {string} [region] - AWS region
+ * @property {Object} [metadata] - Additional discovery metadata
+ */
+
+/**
+ * Create empty discovery result
+ * @returns {DiscoveryResult}
+ */
+function createEmptyDiscoveryResult() {
+    return {
+        stackManaged: [],
+        external: [],
+        fromCloudFormation: false
+    };
+}
+
+/**
+ * Find stack-managed resource by logical ID
+ * @param {DiscoveryResult} discovery - Discovery result
+ * @param {string} logicalId - Logical resource ID to find
+ * @returns {StackManagedResource|null}
+ */
+function findStackResource(discovery, logicalId) {
+    return discovery.stackManaged.find(r => r.logicalId === logicalId) || null;
+}
+
+/**
+ * Find external resource by type
+ * @param {DiscoveryResult} discovery - Discovery result
+ * @param {string} resourceType - CloudFormation resource type
+ * @returns {ExternalResource|null}
+ */
+function findExternalResource(discovery, resourceType) {
+    return discovery.external.find(r => r.resourceType === resourceType) || null;
+}
+
+/**
+ * Find all external resources by type
+ * @param {DiscoveryResult} discovery - Discovery result
+ * @param {string} resourceType - CloudFormation resource type
+ * @returns {ExternalResource[]}
+ */
+function findAllExternalResources(discovery, resourceType) {
+    return discovery.external.filter(r => r.resourceType === resourceType);
+}
+
+/**
+ * Check if specific resource exists in stack
+ * @param {DiscoveryResult} discovery - Discovery result
+ * @param {string} logicalId - Logical resource ID
+ * @returns {boolean}
+ */
+function isResourceInStack(discovery, logicalId) {
+    return discovery.stackManaged.some(r => r.logicalId === logicalId);
+}
+
+/**
+ * Get all stack logical IDs
+ * @param {DiscoveryResult} discovery - Discovery result
+ * @returns {string[]}
+ */
+function getStackLogicalIds(discovery) {
+    return discovery.stackManaged.map(r => r.logicalId);
+}
+
+module.exports = {
+    createEmptyDiscoveryResult,
+    findStackResource,
+    findExternalResource,
+    findAllExternalResources,
+    isResourceInStack,
+    getStackLogicalIds
+};

package/infrastructure/domains/shared/types/discovery-result.test.js

@@ -0,0 +1,258 @@
+const {
+    createEmptyDiscoveryResult,
+    findStackResource,
+    findExternalResource,
+    findAllExternalResources,
+    isResourceInStack,
+    getStackLogicalIds
+} = require('./discovery-result');
+
+describe('Discovery Result Utilities', () => {
+    describe('createEmptyDiscoveryResult', () => {
+        it('should create empty discovery result with correct structure', () => {
+            const result = createEmptyDiscoveryResult();
+
+            expect(result).toEqual({
+                stackManaged: [],
+                external: [],
+                fromCloudFormation: false
+            });
+        });
+    });
+
+    describe('findStackResource', () => {
+        it('should find resource by logical ID', () => {
+            const discovery = {
+                stackManaged: [
+                    { logicalId: 'FriggVPC', physicalId: 'vpc-123', resourceType: 'AWS::EC2::VPC' },
+                    { logicalId: 'FriggLambdaSecurityGroup', physicalId: 'sg-456', resourceType: 'AWS::EC2::SecurityGroup' }
+                ],
+                external: [],
+                fromCloudFormation: true
+            };
+
+            const found = findStackResource(discovery, 'FriggLambdaSecurityGroup');
+
+            expect(found).toEqual({
+                logicalId: 'FriggLambdaSecurityGroup',
+                physicalId: 'sg-456',
+                resourceType: 'AWS::EC2::SecurityGroup'
+            });
+        });
+
+        it('should return null if resource not found', () => {
+            const discovery = {
+                stackManaged: [
+                    { logicalId: 'FriggVPC', physicalId: 'vpc-123', resourceType: 'AWS::EC2::VPC' }
+                ],
+                external: [],
+                fromCloudFormation: true
+            };
+
+            const found = findStackResource(discovery, 'NonExistent');
+
+            expect(found).toBeNull();
+        });
+
+        it('should return null for empty stack managed resources', () => {
+            const discovery = createEmptyDiscoveryResult();
+            const found = findStackResource(discovery, 'FriggVPC');
+
+            expect(found).toBeNull();
+        });
+    });
+
+    describe('findExternalResource', () => {
+        it('should find external resource by type', () => {
+            const discovery = {
+                stackManaged: [],
+                external: [
+                    { physicalId: 'vpc-external', resourceType: 'AWS::EC2::VPC', source: 'tag-search' },
+                    { physicalId: 'sg-external', resourceType: 'AWS::EC2::SecurityGroup', source: 'tag-search' }
+                ],
+                fromCloudFormation: false
+            };
+
+            const found = findExternalResource(discovery, 'AWS::EC2::SecurityGroup');
+
+            expect(found).toEqual({
+                physicalId: 'sg-external',
+                resourceType: 'AWS::EC2::SecurityGroup',
+                source: 'tag-search'
+            });
+        });
+
+        it('should return null if external resource not found', () => {
+            const discovery = createEmptyDiscoveryResult();
+            const found = findExternalResource(discovery, 'AWS::EC2::VPC');
+
+            expect(found).toBeNull();
+        });
+
+        it('should return first match if multiple resources of same type', () => {
+            const discovery = {
+                stackManaged: [],
+                external: [
+                    { physicalId: 'subnet-1', resourceType: 'AWS::EC2::Subnet', source: 'tag-search' },
+                    { physicalId: 'subnet-2', resourceType: 'AWS::EC2::Subnet', source: 'tag-search' }
+                ],
+                fromCloudFormation: false
+            };
+
+            const found = findExternalResource(discovery, 'AWS::EC2::Subnet');
+
+            expect(found.physicalId).toBe('subnet-1');
+        });
+    });
+
+    describe('findAllExternalResources', () => {
+        it('should find all external resources of given type', () => {
+            const discovery = {
+                stackManaged: [],
+                external: [
+                    { physicalId: 'subnet-1', resourceType: 'AWS::EC2::Subnet', source: 'tag-search' },
+                    { physicalId: 'subnet-2', resourceType: 'AWS::EC2::Subnet', source: 'tag-search' },
+                    { physicalId: 'sg-1', resourceType: 'AWS::EC2::SecurityGroup', source: 'tag-search' }
+                ],
+                fromCloudFormation: false
+            };
+
+            const found = findAllExternalResources(discovery, 'AWS::EC2::Subnet');
+
+            expect(found).toHaveLength(2);
+            expect(found[0].physicalId).toBe('subnet-1');
+            expect(found[1].physicalId).toBe('subnet-2');
+        });
+
+        it('should return empty array if no resources found', () => {
+            const discovery = createEmptyDiscoveryResult();
+            const found = findAllExternalResources(discovery, 'AWS::EC2::VPC');
+
+            expect(found).toEqual([]);
+        });
+    });
+
+    describe('isResourceInStack', () => {
+        it('should return true if resource is in stack', () => {
+            const discovery = {
+                stackManaged: [
+                    { logicalId: 'FriggVPC', physicalId: 'vpc-123', resourceType: 'AWS::EC2::VPC' },
+                    { logicalId: 'FriggLambdaSecurityGroup', physicalId: 'sg-456', resourceType: 'AWS::EC2::SecurityGroup' }
+                ],
+                external: [],
+                fromCloudFormation: true
+            };
+
+            expect(isResourceInStack(discovery, 'FriggVPC')).toBe(true);
+            expect(isResourceInStack(discovery, 'FriggLambdaSecurityGroup')).toBe(true);
+        });
+
+        it('should return false if resource is not in stack', () => {
+            const discovery = {
+                stackManaged: [
+                    { logicalId: 'FriggVPC', physicalId: 'vpc-123', resourceType: 'AWS::EC2::VPC' }
+                ],
+                external: [],
+                fromCloudFormation: true
+            };
+
+            expect(isResourceInStack(discovery, 'NonExistent')).toBe(false);
+        });
+
+        it('should return false for empty stack', () => {
+            const discovery = createEmptyDiscoveryResult();
+
+            expect(isResourceInStack(discovery, 'FriggVPC')).toBe(false);
+        });
+    });
+
+    describe('getStackLogicalIds', () => {
+        it('should return all logical IDs from stack', () => {
+            const discovery = {
+                stackManaged: [
+                    { logicalId: 'FriggVPC', physicalId: 'vpc-123', resourceType: 'AWS::EC2::VPC' },
+                    { logicalId: 'FriggLambdaSecurityGroup', physicalId: 'sg-456', resourceType: 'AWS::EC2::SecurityGroup' },
+                    { logicalId: 'FriggAuroraCluster', physicalId: 'cluster-789', resourceType: 'AWS::RDS::DBCluster' }
+                ],
+                external: [],
+                fromCloudFormation: true
+            };
+
+            const ids = getStackLogicalIds(discovery);
+
+            expect(ids).toEqual([
+                'FriggVPC',
+                'FriggLambdaSecurityGroup',
+                'FriggAuroraCluster'
+            ]);
+        });
+
+        it('should return empty array for empty stack', () => {
+            const discovery = createEmptyDiscoveryResult();
+            const ids = getStackLogicalIds(discovery);
+
+            expect(ids).toEqual([]);
+        });
+    });
+
+    describe('real-world scenarios', () => {
+        it('scenario: fresh deploy, no stack exists', () => {
+            const discovery = createEmptyDiscoveryResult();
+
+            expect(discovery.fromCloudFormation).toBe(false);
+            expect(discovery.stackManaged).toHaveLength(0);
+            expect(discovery.external).toHaveLength(0);
+
+            expect(isResourceInStack(discovery, 'FriggVPC')).toBe(false);
+            expect(findStackResource(discovery, 'FriggVPC')).toBeNull();
+        });
+
+        it('scenario: redeploy existing stack', () => {
+            const discovery = {
+                stackManaged: [
+                    { logicalId: 'FriggVPC', physicalId: 'vpc-123', resourceType: 'AWS::EC2::VPC' },
+                    { logicalId: 'FriggLambdaSecurityGroup', physicalId: 'sg-069629001ade41c9a', resourceType: 'AWS::EC2::SecurityGroup' },
+                    { logicalId: 'FriggPrivateSubnet1', physicalId: 'subnet-1', resourceType: 'AWS::EC2::Subnet' },
+                    { logicalId: 'FriggPrivateSubnet2', physicalId: 'subnet-2', resourceType: 'AWS::EC2::Subnet' },
+                    { logicalId: 'FriggAuroraCluster', physicalId: 'cluster-abc', resourceType: 'AWS::RDS::DBCluster' },
+                    { logicalId: 'FriggKMSKey', physicalId: 'key-xyz', resourceType: 'AWS::KMS::Key' }
+                ],
+                external: [],
+                fromCloudFormation: true,
+                stackName: 'create-frigg-app-production'
+            };
+
+            expect(discovery.fromCloudFormation).toBe(true);
+            expect(discovery.stackManaged).toHaveLength(6);
+
+            // All these resources are in stack - MUST be kept in template
+            expect(isResourceInStack(discovery, 'FriggLambdaSecurityGroup')).toBe(true);
+            expect(isResourceInStack(discovery, 'FriggAuroraCluster')).toBe(true);
+
+            const sg = findStackResource(discovery, 'FriggLambdaSecurityGroup');
+            expect(sg.physicalId).toBe('sg-069629001ade41c9a');
+        });
+
+        it('scenario: use external VPC with stack-managed resources', () => {
+            const discovery = {
+                stackManaged: [
+                    { logicalId: 'FriggLambdaSecurityGroup', physicalId: 'sg-456', resourceType: 'AWS::EC2::SecurityGroup' },
+                    { logicalId: 'FriggPrivateSubnet1', physicalId: 'subnet-1', resourceType: 'AWS::EC2::Subnet' }
+                ],
+                external: [
+                    { physicalId: 'vpc-external', resourceType: 'AWS::EC2::VPC', source: 'user-provided' }
+                ],
+                fromCloudFormation: true,
+                stackName: 'my-app-dev'
+            };
+
+            // VPC is external - should NOT be in template
+            expect(isResourceInStack(discovery, 'FriggVPC')).toBe(false);
+            const externalVpc = findExternalResource(discovery, 'AWS::EC2::VPC');
+            expect(externalVpc.physicalId).toBe('vpc-external');
+
+            // But security group IS in stack - MUST be in template
+            expect(isResourceInStack(discovery, 'FriggLambdaSecurityGroup')).toBe(true);
+        });
+    });
+});

package/infrastructure/domains/shared/types/index.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Central export for all infrastructure types
+ */
+
+const { ResourceOwnership, validateOwnership, resolveOwnership } = require('./resource-ownership');
+
+const {
+    createEmptyDiscoveryResult,
+    findStackResource,
+    findExternalResource,
+    findAllExternalResources,
+    isResourceInStack,
+    getStackLogicalIds
+} = require('./discovery-result');
+
+const {
+    validateAppDefinition,
+    getStackName,
+    isVpcEnabled,
+    isAuroraEnabled,
+    isKmsEnabled,
+    isSsmEnabled
+} = require('./app-definition');
+
+module.exports = {
+    // Resource Ownership
+    ResourceOwnership,
+    validateOwnership,
+    resolveOwnership,
+
+    // Discovery Result
+    createEmptyDiscoveryResult,
+    findStackResource,
+    findExternalResource,
+    findAllExternalResources,
+    isResourceInStack,
+    getStackLogicalIds,
+
+    // App Definition
+    validateAppDefinition,
+    getStackName,
+    isVpcEnabled,
+    isAuroraEnabled,
+    isKmsEnabled,
+    isSsmEnabled
+};