@friggframework/devtools 2.0.0--canary.474.6ec870b.0 → 2.0.0--canary.474.d64c550.0

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;

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

@@ -0,0 +1,142 @@
+/**
+ * IResourceImporter Port Interface
+ *
+ * Defines operations for importing existing cloud resources into CloudFormation stacks.
+ * This is used by the "frigg repair --import" command to fix orphaned resources.
+ *
+ * This is a port in the hexagonal architecture that will be implemented
+ * by provider-specific adapters (e.g., AWSResourceImporter).
+ *
+ * Purpose: Abstract CloudFormation resource import operations from the domain layer
+ */
+
+class IResourceImporter {
+    /**
+     * Check if a resource type supports import
+     *
+     * @param {string} resourceType - CloudFormation resource type (e.g., AWS::EC2::VPC)
+     * @returns {Promise<boolean>} True if resource type can be imported
+     */
+    async supportsImport(resourceType) {
+        throw new Error(
+            'IResourceImporter.supportsImport() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Get the identifier property for a resource type
+     * (e.g., "VpcId" for AWS::EC2::VPC, "BucketName" for AWS::S3::Bucket)
+     *
+     * @param {string} resourceType - CloudFormation resource type
+     * @returns {Promise<string>} Property name used as identifier for import
+     * @throws {Error} If resource type doesn't support import
+     */
+    async getIdentifierProperty(resourceType) {
+        throw new Error(
+            'IResourceImporter.getIdentifierProperty() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Validate that a resource can be imported
+     *
+     * @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>} Validation result
+     * @returns {Promise<Object>} Result with properties:
+     *   - canImport: boolean
+     *   - reason: string (explanation if cannot import)
+     *   - warnings: Array<string> (potential issues with import)
+     */
+    async validateImport({ resourceType, physicalId, region }) {
+        throw new Error(
+            'IResourceImporter.validateImport() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Import a single resource into a stack
+     *
+     * @param {Object} params
+     * @param {StackIdentifier} params.stackIdentifier - Target stack
+     * @param {string} params.logicalId - Desired logical ID for the resource
+     * @param {string} params.resourceType - CloudFormation resource type
+     * @param {string} params.physicalId - Physical resource ID to import
+     * @param {Object} params.properties - Resource properties for template
+     * @returns {Promise<Object>} Import operation result
+     * @returns {Promise<Object>} Result with properties:
+     *   - operationId: string (CloudFormation change set ID)
+     *   - status: string (IN_PROGRESS, COMPLETE, FAILED)
+     *   - message: string (status message)
+     * @throws {Error} If import fails validation or execution
+     */
+    async importResource({ stackIdentifier, logicalId, resourceType, physicalId, properties }) {
+        throw new Error(
+            'IResourceImporter.importResource() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Import multiple resources into a stack in a single operation
+     *
+     * @param {Object} params
+     * @param {StackIdentifier} params.stackIdentifier - Target stack
+     * @param {Array<Object>} params.resources - Resources to import
+     * @param {string} params.resources[].logicalId - Desired logical ID
+     * @param {string} params.resources[].resourceType - CloudFormation resource type
+     * @param {string} params.resources[].physicalId - Physical resource ID
+     * @param {Object} params.resources[].properties - Resource properties
+     * @returns {Promise<Object>} Import operation result
+     * @returns {Promise<Object>} Result with properties:
+     *   - operationId: string (CloudFormation change set ID)
+     *   - status: string (IN_PROGRESS, COMPLETE, FAILED)
+     *   - importedCount: number
+     *   - failedCount: number
+     *   - message: string
+     *   - details: Array<Object> (per-resource status)
+     * @throws {Error} If import fails validation or execution
+     */
+    async importMultipleResources({ stackIdentifier, resources }) {
+        throw new Error(
+            'IResourceImporter.importMultipleResources() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Get status of an import operation
+     *
+     * @param {string} operationId - CloudFormation change set ID
+     * @returns {Promise<Object>} Operation status
+     * @returns {Promise<Object>} Status with properties:
+     *   - operationId: string
+     *   - status: string (IN_PROGRESS, COMPLETE, FAILED)
+     *   - progress: number (0-100)
+     *   - message: string
+     *   - completedTime: Date (if complete)
+     */
+    async getImportStatus(operationId) {
+        throw new Error(
+            'IResourceImporter.getImportStatus() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Generate CloudFormation template snippet for an imported resource
+     *
+     * @param {Object} params
+     * @param {string} params.logicalId - Logical ID for the resource
+     * @param {string} params.resourceType - CloudFormation resource type
+     * @param {Object} params.properties - Current resource properties from cloud
+     * @returns {Promise<Object>} Template snippet for the resource
+     * @returns {Promise<Object>} Template snippet with CloudFormation resource definition
+     */
+    async generateTemplateSnippet({ logicalId, resourceType, properties }) {
+        throw new Error(
+            'IResourceImporter.generateTemplateSnippet() must be implemented by adapter'
+        );
+    }
+}
+
+module.exports = IResourceImporter;

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

@@ -0,0 +1,131 @@
+/**
+ * IStackRepository Port Interface
+ *
+ * Defines operations for accessing CloudFormation stack information.
+ * This is a port in the hexagonal architecture that will be implemented
+ * by provider-specific adapters (e.g., AWSStackRepository).
+ *
+ * Purpose: Abstract CloudFormation API interactions from the domain layer
+ */
+
+class IStackRepository {
+    /**
+     * Get stack information by identifier
+     *
+     * @param {StackIdentifier} identifier - Stack identifier
+     * @returns {Promise<Object>} Stack information
+     * @returns {Promise<Object>} Stack information with properties:
+     *   - stackName: string
+     *   - region: string
+     *   - accountId: string
+     *   - stackId: string (ARN)
+     *   - status: string (CREATE_COMPLETE, UPDATE_COMPLETE, etc.)
+     *   - creationTime: Date
+     *   - lastUpdatedTime: Date
+     *   - parameters: Object (key-value pairs)
+     *   - outputs: Object (key-value pairs)
+     *   - tags: Object (key-value pairs)
+     * @throws {Error} If stack does not exist
+     */
+    async getStack(identifier) {
+        throw new Error('IStackRepository.getStack() must be implemented by adapter');
+    }
+
+    /**
+     * List all resources in a stack
+     *
+     * @param {StackIdentifier} identifier - Stack identifier
+     * @returns {Promise<Array>} Array of stack resources
+     * @returns {Promise<Array<Object>>} Array of resources with properties:
+     *   - logicalId: string (CloudFormation logical ID)
+     *   - physicalId: string (actual cloud resource ID)
+     *   - resourceType: string (e.g., AWS::EC2::VPC)
+     *   - status: string (CREATE_COMPLETE, UPDATE_COMPLETE, etc.)
+     *   - lastUpdatedTime: Date
+     *   - driftStatus: string (IN_SYNC, MODIFIED, DELETED, NOT_CHECKED)
+     * @throws {Error} If stack does not exist
+     */
+    async listResources(identifier) {
+        throw new Error(
+            'IStackRepository.listResources() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Get resource details from stack
+     *
+     * @param {StackIdentifier} identifier - Stack identifier
+     * @param {string} logicalId - Logical resource ID
+     * @returns {Promise<Object>} Resource details
+     * @returns {Promise<Object>} Resource with properties:
+     *   - logicalId: string
+     *   - physicalId: string
+     *   - resourceType: string
+     *   - status: string
+     *   - properties: Object (current resource properties)
+     *   - metadata: Object (resource metadata from template)
+     * @throws {Error} If stack or resource does not exist
+     */
+    async getResource(identifier, logicalId) {
+        throw new Error('IStackRepository.getResource() must be implemented by adapter');
+    }
+
+    /**
+     * Get the CloudFormation template for a stack
+     *
+     * @param {StackIdentifier} identifier - Stack identifier
+     * @returns {Promise<Object>} CloudFormation template as object
+     * @throws {Error} If stack does not exist
+     */
+    async getTemplate(identifier) {
+        throw new Error('IStackRepository.getTemplate() must be implemented by adapter');
+    }
+
+    /**
+     * Check if a stack exists
+     *
+     * @param {StackIdentifier} identifier - Stack identifier
+     * @returns {Promise<boolean>} True if stack exists
+     */
+    async exists(identifier) {
+        throw new Error('IStackRepository.exists() must be implemented by adapter');
+    }
+
+    /**
+     * Detect drift for the entire stack
+     *
+     * @param {StackIdentifier} identifier - Stack identifier
+     * @returns {Promise<Object>} Drift detection result
+     * @returns {Promise<Object>} Result with properties:
+     *   - stackDriftStatus: string (DRIFTED, IN_SYNC, UNKNOWN, NOT_CHECKED)
+     *   - driftedResourceCount: number
+     *   - detectionTime: Date
+     * @throws {Error} If stack does not exist
+     */
+    async detectStackDrift(identifier) {
+        throw new Error(
+            'IStackRepository.detectStackDrift() must be implemented by adapter'
+        );
+    }
+
+    /**
+     * Get drift details for a specific resource
+     *
+     * @param {StackIdentifier} identifier - Stack identifier
+     * @param {string} logicalId - Logical resource ID
+     * @returns {Promise<Object>} Resource drift details
+     * @returns {Promise<Object>} Drift with properties:
+     *   - driftStatus: string (IN_SYNC, MODIFIED, DELETED, NOT_CHECKED)
+     *   - expectedProperties: Object (from template)
+     *   - actualProperties: Object (from cloud)
+     *   - propertyDifferences: Array<Object> (list of drifted properties)
+     * @throws {Error} If stack or resource does not exist
+     */
+    async getResourceDrift(identifier, logicalId) {
+        throw new Error(
+            'IStackRepository.getResourceDrift() must be implemented by adapter'
+        );
+    }
+}
+
+module.exports = IStackRepository;

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

@@ -0,0 +1,26 @@
+/**
+ * Health Domain - Application Layer Ports
+ *
+ * Port interfaces define how the application layer communicates with
+ * infrastructure adapters. These are part of the hexagonal architecture
+ * pattern, allowing provider-specific implementations (AWS, GCP, Azure, etc.)
+ * without changing the domain or application logic.
+ *
+ * Ports:
+ * - IStackRepository: CloudFormation stack operations
+ * - IResourceDetector: Cloud resource discovery (orphan detection)
+ * - IResourceImporter: Import resources into CloudFormation
+ * - IPropertyReconciler: Fix property drift (mutable properties)
+ */
+
+const IStackRepository = require('./IStackRepository');
+const IResourceDetector = require('./IResourceDetector');
+const IResourceImporter = require('./IResourceImporter');
+const IPropertyReconciler = require('./IPropertyReconciler');
+
+module.exports = {
+    IStackRepository,
+    IResourceDetector,
+    IResourceImporter,
+    IPropertyReconciler,
+};