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

package/infrastructure/domains/database/migration-resolver.test.js

@@ -0,0 +1,337 @@
+const { MigrationResourceResolver } = require('./migration-resolver');
+const { ResourceOwnership, createEmptyDiscoveryResult } = require('../shared/types');
+
+describe('MigrationResourceResolver', () => {
+    let resolver;
+
+    beforeEach(() => {
+        resolver = new MigrationResourceResolver();
+    });
+
+    describe('resolveBucket', () => {
+        describe('Explicit ownership intent', () => {
+            it('should respect ownership.bucket=stack when specified', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { bucket: 'stack' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+
+                const decision = resolver.resolveBucket(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBeNull();
+                expect(decision.reason).toContain('Will create FriggMigrationStatusBucket in stack');
+            });
+
+            it('should respect ownership.bucket=external when bucket discovered', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { bucket: 'external' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+                discovery.external.push({
+                    physicalId: 'my-migration-bucket',
+                    resourceType: 'AWS::S3::Bucket',
+                    source: 'aws-discovery'
+                });
+
+                const decision = resolver.resolveBucket(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+                expect(decision.physicalId).toBe('my-migration-bucket');
+                expect(decision.reason).toContain('external');
+            });
+
+            it('should error when ownership.bucket=external but no bucket discovered', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { bucket: 'external' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+
+                expect(() => resolver.resolveBucket(appDefinition, discovery))
+                    .toThrow('ownership.bucket=external but no S3 bucket discovered');
+            });
+        });
+
+        describe('Auto resolution (ownership.bucket=auto)', () => {
+            it('should use stack bucket when found in CloudFormation', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { bucket: 'auto' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+                discovery.fromCloudFormation = true;
+                discovery.stackManaged.push({
+                    logicalId: 'FriggMigrationStatusBucket',
+                    physicalId: 'stack-migration-bucket',
+                    resourceType: 'AWS::S3::Bucket'
+                });
+
+                const decision = resolver.resolveBucket(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBe('stack-migration-bucket');
+                expect(decision.reason).toContain('Found FriggMigrationStatusBucket in CloudFormation stack');
+            });
+
+            it('should use external bucket when found via discovery', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { bucket: 'auto' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+                discovery.external.push({
+                    physicalId: 'external-migration-bucket',
+                    resourceType: 'AWS::S3::Bucket',
+                    source: 'aws-discovery'
+                });
+
+                const decision = resolver.resolveBucket(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+                expect(decision.physicalId).toBe('external-migration-bucket');
+                expect(decision.reason).toContain('Found external S3 bucket via discovery');
+            });
+
+            it('should create new bucket when none found', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { bucket: 'auto' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+
+                const decision = resolver.resolveBucket(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBeNull();
+                expect(decision.reason).toContain('No existing migration bucket - will create in stack');
+            });
+        });
+
+        describe('Default behavior (no ownership specified)', () => {
+            it('should default to auto resolution', () => {
+                const appDefinition = {};
+                const discovery = createEmptyDiscoveryResult();
+
+                const decision = resolver.resolveBucket(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.reason).toContain('No existing migration bucket - will create in stack');
+            });
+        });
+    });
+
+    describe('resolveQueue', () => {
+        describe('Explicit ownership intent', () => {
+            it('should respect ownership.queue=stack when specified', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { queue: 'stack' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+
+                const decision = resolver.resolveQueue(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBeNull();
+                expect(decision.reason).toContain('Will create DbMigrationQueue in stack');
+            });
+
+            it('should respect ownership.queue=external when queue discovered', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { queue: 'external' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+                discovery.external.push({
+                    physicalId: 'https://sqs.us-east-1.amazonaws.com/123456789/my-migration-queue',
+                    resourceType: 'AWS::SQS::Queue',
+                    source: 'aws-discovery'
+                });
+
+                const decision = resolver.resolveQueue(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+                expect(decision.physicalId).toBe('https://sqs.us-east-1.amazonaws.com/123456789/my-migration-queue');
+                expect(decision.reason).toContain('external');
+            });
+
+            it('should error when ownership.queue=external but no queue discovered', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { queue: 'external' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+
+                expect(() => resolver.resolveQueue(appDefinition, discovery))
+                    .toThrow('ownership.queue=external but no SQS queue discovered');
+            });
+        });
+
+        describe('Auto resolution (ownership.queue=auto)', () => {
+            it('should use stack queue when found in CloudFormation', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { queue: 'auto' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+                discovery.fromCloudFormation = true;
+                discovery.stackManaged.push({
+                    logicalId: 'DbMigrationQueue',
+                    physicalId: 'https://sqs.us-east-1.amazonaws.com/123456789/stack-migration-queue',
+                    resourceType: 'AWS::SQS::Queue'
+                });
+
+                const decision = resolver.resolveQueue(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBe('https://sqs.us-east-1.amazonaws.com/123456789/stack-migration-queue');
+                expect(decision.reason).toContain('Found DbMigrationQueue in CloudFormation stack');
+            });
+
+            it('should use external queue when found via discovery', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { queue: 'auto' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+                discovery.external.push({
+                    physicalId: 'https://sqs.us-east-1.amazonaws.com/123456789/external-migration-queue',
+                    resourceType: 'AWS::SQS::Queue',
+                    source: 'aws-discovery'
+                });
+
+                const decision = resolver.resolveQueue(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+                expect(decision.physicalId).toBe('https://sqs.us-east-1.amazonaws.com/123456789/external-migration-queue');
+                expect(decision.reason).toContain('Found external SQS queue via discovery');
+            });
+
+            it('should create new queue when none found', () => {
+                const appDefinition = {
+                    migration: {
+                        ownership: { queue: 'auto' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+
+                const decision = resolver.resolveQueue(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBeNull();
+                expect(decision.reason).toContain('No existing migration queue - will create in stack');
+            });
+        });
+    });
+
+    describe('resolveAll', () => {
+        it('should return decisions for all migration resources', () => {
+            const appDefinition = {
+                database: {
+                    postgres: {
+                        enable: true
+                    }
+                }
+            };
+            const discovery = createEmptyDiscoveryResult();
+
+            const decisions = resolver.resolveAll(appDefinition, discovery);
+
+            expect(decisions).toHaveProperty('bucket');
+            expect(decisions).toHaveProperty('queue');
+            expect(decisions.bucket.ownership).toBe(ResourceOwnership.STACK);
+            expect(decisions.queue.ownership).toBe(ResourceOwnership.STACK);
+        });
+    });
+
+    describe('Real-world scenarios', () => {
+        it('should handle managementMode=managed scenario (create resources)', () => {
+            // In managed mode, we want to create resources in stack
+            const appDefinition = {
+                managementMode: 'managed',
+                migration: {
+                    ownership: { bucket: 'stack', queue: 'stack' }
+                }
+            };
+            const discovery = createEmptyDiscoveryResult();
+
+            const decisions = resolver.resolveAll(appDefinition, discovery);
+
+            expect(decisions.bucket.ownership).toBe(ResourceOwnership.STACK);
+            expect(decisions.bucket.physicalId).toBeNull();
+            expect(decisions.queue.ownership).toBe(ResourceOwnership.STACK);
+            expect(decisions.queue.physicalId).toBeNull();
+        });
+
+        it('should handle existing stack resources (reuse)', () => {
+            // Stack already has migration resources from previous deployment
+            const appDefinition = {
+                migration: {
+                    ownership: { bucket: 'auto', queue: 'auto' }
+                }
+            };
+            const discovery = createEmptyDiscoveryResult();
+            discovery.fromCloudFormation = true;
+            discovery.stackManaged.push({
+                logicalId: 'FriggMigrationStatusBucket',
+                physicalId: 'my-stack-bucket',
+                resourceType: 'AWS::S3::Bucket'
+            });
+            discovery.stackManaged.push({
+                logicalId: 'DbMigrationQueue',
+                physicalId: 'https://sqs.us-east-1.amazonaws.com/123/my-queue',
+                resourceType: 'AWS::SQS::Queue'
+            });
+
+            const decisions = resolver.resolveAll(appDefinition, discovery);
+
+            expect(decisions.bucket.ownership).toBe(ResourceOwnership.STACK);
+            expect(decisions.bucket.physicalId).toBe('my-stack-bucket');
+            expect(decisions.queue.ownership).toBe(ResourceOwnership.STACK);
+            expect(decisions.queue.physicalId).toBe('https://sqs.us-east-1.amazonaws.com/123/my-queue');
+        });
+
+        it('should handle shared migration resources scenario', () => {
+            // Using shared infrastructure migration resources
+            const appDefinition = {
+                managementMode: 'managed',
+                vpcIsolation: 'shared',
+                migration: {
+                    ownership: { bucket: 'auto', queue: 'auto' }
+                }
+            };
+            const discovery = createEmptyDiscoveryResult();
+            discovery.external.push({
+                physicalId: 'shared-migration-bucket',
+                resourceType: 'AWS::S3::Bucket',
+                source: 'aws-discovery'
+            });
+            discovery.external.push({
+                physicalId: 'https://sqs.us-east-1.amazonaws.com/123/shared-queue',
+                resourceType: 'AWS::SQS::Queue',
+                source: 'aws-discovery'
+            });
+
+            const decisions = resolver.resolveAll(appDefinition, discovery);
+
+            expect(decisions.bucket.ownership).toBe(ResourceOwnership.EXTERNAL);
+            expect(decisions.bucket.physicalId).toBe('shared-migration-bucket');
+            expect(decisions.queue.ownership).toBe(ResourceOwnership.EXTERNAL);
+            expect(decisions.queue.physicalId).toBe('https://sqs.us-east-1.amazonaws.com/123/shared-queue');
+        });
+    });
+});

package/infrastructure/domains/health/application/ports/IPropertyReconciler.js

@@ -0,0 +1,164 @@
+/**
+ * IPropertyReconciler Port Interface
+ *
+ * Defines operations for reconciling property mismatches between CloudFormation
+ * template definitions and actual cloud resource properties. This is used by
+ * the "frigg repair --reconcile" command to fix mutable property drift.
+ *
+ * This is a port in the hexagonal architecture that will be implemented
+ * by provider-specific adapters (e.g., AWSPropertyReconciler).
+ *
+ * Purpose: Abstract property update operations from the domain layer
+ */
+
+class IPropertyReconciler {
+    /**
+     * Check if a property mismatch can be auto-fixed
+     *
+     * @param {PropertyMismatch} mismatch - Property mismatch to evaluate
+     * @returns {Promise<boolean>} True if mismatch can be automatically fixed
+     */
+    async canReconcile(mismatch) {
+        throw new Error(
+            'IPropertyReconciler.canReconcile() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Reconcile a single property mismatch
+     *
+     * @param {Object} params
+     * @param {StackIdentifier} params.stackIdentifier - Stack identifier
+     * @param {string} params.logicalId - Logical resource ID
+     * @param {PropertyMismatch} params.mismatch - Property mismatch to fix
+     * @param {string} [params.mode='template'] - Reconciliation mode:
+     *   - 'template': Update CloudFormation template to match actual (default)
+     *   - 'resource': Update cloud resource to match template
+     * @returns {Promise<Object>} Reconciliation result
+     * @returns {Promise<Object>} Result with properties:
+     *   - success: boolean
+     *   - mode: string ('template' or 'resource')
+     *   - propertyPath: string
+     *   - oldValue: any
+     *   - newValue: any
+     *   - message: string
+     * @throws {Error} If reconciliation fails
+     */
+    async reconcileProperty({ stackIdentifier, logicalId, mismatch, mode = 'template' }) {
+        throw new Error(
+            'IPropertyReconciler.reconcileProperty() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Reconcile multiple property mismatches for a resource
+     *
+     * @param {Object} params
+     * @param {StackIdentifier} params.stackIdentifier - Stack identifier
+     * @param {string} params.logicalId - Logical resource ID
+     * @param {PropertyMismatch[]} params.mismatches - Property mismatches to fix
+     * @param {string} [params.mode='template'] - Reconciliation mode
+     * @returns {Promise<Object>} Reconciliation result
+     * @returns {Promise<Object>} Result with properties:
+     *   - reconciledCount: number
+     *   - failedCount: number
+     *   - results: Array<Object> (per-property results)
+     *   - message: string
+     */
+    async reconcileMultipleProperties({
+        stackIdentifier,
+        logicalId,
+        mismatches,
+        mode = 'template',
+    }) {
+        throw new Error(
+            'IPropertyReconciler.reconcileMultipleProperties() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Preview property reconciliation without applying changes
+     *
+     * @param {Object} params
+     * @param {StackIdentifier} params.stackIdentifier - Stack identifier
+     * @param {string} params.logicalId - Logical resource ID
+     * @param {PropertyMismatch} params.mismatch - Property mismatch to preview
+     * @param {string} [params.mode='template'] - Reconciliation mode
+     * @returns {Promise<Object>} Preview result
+     * @returns {Promise<Object>} Result with properties:
+     *   - canReconcile: boolean
+     *   - mode: string
+     *   - propertyPath: string
+     *   - currentValue: any
+     *   - proposedValue: any
+     *   - impact: string (description of impact)
+     *   - warnings: Array<string>
+     */
+    async previewReconciliation({ stackIdentifier, logicalId, mismatch, mode = 'template' }) {
+        throw new Error(
+            'IPropertyReconciler.previewReconciliation() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Update CloudFormation template property
+     *
+     * @param {Object} params
+     * @param {StackIdentifier} params.stackIdentifier - Stack identifier
+     * @param {string} params.logicalId - Logical resource ID
+     * @param {string} params.propertyPath - Property path (e.g., "Properties.Tags")
+     * @param {*} params.newValue - New property value
+     * @returns {Promise<Object>} Update result
+     * @returns {Promise<Object>} Result with properties:
+     *   - success: boolean
+     *   - changeSetId: string (CloudFormation change set ID)
+     *   - message: string
+     * @throws {Error} If update fails
+     */
+    async updateTemplateProperty({ stackIdentifier, logicalId, propertyPath, newValue }) {
+        throw new Error(
+            'IPropertyReconciler.updateTemplateProperty() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Update cloud resource property directly
+     *
+     * @param {Object} params
+     * @param {string} params.resourceType - CloudFormation resource type
+     * @param {string} params.physicalId - Physical resource ID
+     * @param {string} params.region - AWS region
+     * @param {string} params.propertyPath - Property path
+     * @param {*} params.newValue - New property value
+     * @returns {Promise<Object>} Update result
+     * @returns {Promise<Object>} Result with properties:
+     *   - success: boolean
+     *   - message: string
+     *   - updatedAt: Date
+     * @throws {Error} If update fails or is not supported
+     */
+    async updateResourceProperty({ resourceType, physicalId, region, propertyPath, newValue }) {
+        throw new Error(
+            'IPropertyReconciler.updateResourceProperty() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Get reconciliation strategy for a resource type
+     *
+     * @param {string} resourceType - CloudFormation resource type
+     * @returns {Promise<Object>} Strategy information
+     * @returns {Promise<Object>} Strategy with properties:
+     *   - supportsTemplateUpdate: boolean
+     *   - supportsResourceUpdate: boolean
+     *   - recommendedMode: string ('template' or 'resource')
+     *   - limitations: Array<string>
+     */
+    async getReconciliationStrategy(resourceType) {
+        throw new Error(
+            'IPropertyReconciler.getReconciliationStrategy() must be implemented by adapter'
+        );
+    }
+}
+
+module.exports = IPropertyReconciler;

package/infrastructure/domains/health/application/ports/IResourceDetector.js

@@ -0,0 +1,129 @@
+/**
+ * IResourceDetector Port Interface
+ *
+ * Defines operations for detecting cloud resources directly (outside of CloudFormation).
+ * This is used to find orphaned resources that exist in the cloud but are not managed
+ * by CloudFormation.
+ *
+ * This is a port in the hexagonal architecture that will be implemented
+ * by provider-specific adapters (e.g., AWSResourceDetector).
+ *
+ * Purpose: Abstract cloud resource discovery APIs from the domain layer
+ */
+
+class IResourceDetector {
+    /**
+     * Detect all resources of a specific type in a region
+     *
+     * @param {Object} params
+     * @param {string} params.resourceType - CloudFormation resource type (e.g., AWS::EC2::VPC)
+     * @param {string} params.region - AWS region
+     * @param {Object} [params.filters={}] - Optional filters (e.g., tags, names)
+     * @returns {Promise<Array<Object>>} Array of detected resources
+     * @returns {Promise<Array<Object>>} Resources with properties:
+     *   - physicalId: string (actual cloud resource ID)
+     *   - resourceType: string (CloudFormation resource type)
+     *   - properties: Object (resource properties from cloud API)
+     *   - tags: Object (resource tags, if supported)
+     *   - createdTime: Date (if available)
+     * @throws {Error} If resource type is not supported
+     */
+    async detectResources({ resourceType, region, filters = {} }) {
+        throw new Error(
+            'IResourceDetector.detectResources() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Get details for a specific resource
+     *
+     * @param {Object} params
+     * @param {string} params.resourceType - CloudFormation resource type
+     * @param {string} params.physicalId - Physical resource ID
+     * @param {string} params.region - AWS region
+     * @returns {Promise<Object>} Resource details
+     * @returns {Promise<Object>} Resource with properties:
+     *   - physicalId: string
+     *   - resourceType: string
+     *   - properties: Object (complete resource properties)
+     *   - tags: Object
+     *   - status: string (resource-specific status)
+     *   - metadata: Object (additional resource metadata)
+     * @throws {Error} If resource does not exist
+     */
+    async getResourceDetails({ resourceType, physicalId, region }) {
+        throw new Error(
+            'IResourceDetector.getResourceDetails() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Check if a resource exists
+     *
+     * @param {Object} params
+     * @param {string} params.resourceType - CloudFormation resource type
+     * @param {string} params.physicalId - Physical resource ID
+     * @param {string} params.region - AWS region
+     * @returns {Promise<boolean>} True if resource exists
+     */
+    async resourceExists({ resourceType, physicalId, region }) {
+        throw new Error(
+            'IResourceDetector.resourceExists() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Get list of supported resource types
+     *
+     * @returns {Promise<Array<string>>} Array of supported CloudFormation resource types
+     */
+    async getSupportedResourceTypes() {
+        throw new Error(
+            'IResourceDetector.getSupportedResourceTypes() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Detect resources by tags
+     *
+     * @param {Object} params
+     * @param {Object} params.tags - Tags to filter by (key-value pairs)
+     * @param {string} params.region - AWS region
+     * @param {string[]} [params.resourceTypes] - Optional: limit to specific resource types
+     * @returns {Promise<Array<Object>>} Array of resources matching tags
+     * @returns {Promise<Array<Object>>} Resources with properties:
+     *   - physicalId: string
+     *   - resourceType: string
+     *   - properties: Object
+     *   - tags: Object
+     */
+    async detectResourcesByTags({ tags, region, resourceTypes = [] }) {
+        throw new Error(
+            'IResourceDetector.detectResourcesByTags() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Find orphaned resources (exist in cloud but not in any stack)
+     *
+     * @param {Object} params
+     * @param {string} params.region - AWS region
+     * @param {string[]} [params.resourceTypes] - Optional: limit to specific resource types
+     * @param {string[]} [params.excludePhysicalIds=[]] - Physical IDs to exclude from orphan check
+     * @returns {Promise<Array<Object>>} Array of orphaned resources
+     * @returns {Promise<Array<Object>>} Resources with properties:
+     *   - physicalId: string
+     *   - resourceType: string
+     *   - properties: Object
+     *   - tags: Object
+     *   - isOrphaned: boolean (always true)
+     *   - reason: string (explanation of why it's orphaned)
+     */
+    async findOrphanedResources({ region, resourceTypes = [], excludePhysicalIds = [] }) {
+        throw new Error(
+            'IResourceDetector.findOrphanedResources() must be implemented by adapter'
+        );
+    }
+}
+
+module.exports = IResourceDetector;