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

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,
+};