@friggframework/core 2.0.0--canary.461.e58db0a.0 → 2.0.0--canary.461.4f3c330.0

package/database/use-cases/get-migration-status-use-case.js

@@ -0,0 +1,97 @@
+/**
+ * Get Migration Status Use Case
+ *
+ * Retrieves the status of a database migration by process ID.
+ * Formats the Process record for migration-specific response.
+ *
+ * This use case follows the Frigg hexagonal architecture pattern where:
+ * - Routers (adapters) call use cases
+ * - Use cases contain business logic and formatting
+ * - Use cases call repositories for data access
+ */
+
+class GetMigrationStatusUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {Object} dependencies.processRepository - Repository for process data access
+     */
+    constructor({ processRepository }) {
+        if (!processRepository) {
+            throw new Error('processRepository dependency is required');
+        }
+        this.processRepository = processRepository;
+    }
+
+    /**
+     * Execute get migration status
+     *
+     * @param {Object} params
+     * @param {string} params.processId - Process ID to retrieve
+     * @returns {Promise<Object>} Migration status with process details
+     * @throws {NotFoundError} If process not found
+     * @throws {Error} If process is not a migration process
+     */
+    async execute({ processId }) {
+        // Validation
+        if (!processId) {
+            throw new ValidationError('processId is required');
+        }
+
+        if (typeof processId !== 'string') {
+            throw new ValidationError('processId must be a string');
+        }
+
+        // Get process from repository
+        const process = await this.processRepository.findById(processId);
+
+        if (!process) {
+            throw new NotFoundError(`Migration process not found: ${processId}`);
+        }
+
+        // Verify this is a migration process
+        if (process.type !== 'DATABASE_MIGRATION') {
+            throw new Error(
+                `Process ${processId} is not a migration process (type: ${process.type})`
+            );
+        }
+
+        // Format response
+        return {
+            processId: process.id,
+            type: process.type,
+            state: process.state,
+            context: process.context || {},
+            results: process.results || {},
+            createdAt: process.createdAt,
+            updatedAt: process.updatedAt,
+        };
+    }
+}
+
+/**
+ * Custom error for validation failures
+ */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+/**
+ * Custom error for not found resources
+ */
+class NotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotFoundError';
+        this.statusCode = 404;
+    }
+}
+
+module.exports = {
+    GetMigrationStatusUseCase,
+    ValidationError,
+    NotFoundError,
+};
+

package/database/use-cases/get-migration-status-use-case.test.js

@@ -0,0 +1,215 @@
+/**
+ * Tests for GetMigrationStatusUseCase
+ */
+
+const {
+    GetMigrationStatusUseCase,
+    ValidationError,
+    NotFoundError,
+} = require('./get-migration-status-use-case');
+
+describe('GetMigrationStatusUseCase', () => {
+    let useCase;
+    let mockProcessRepository;
+
+    beforeEach(() => {
+        // Create mock repository
+        mockProcessRepository = {
+            findById: jest.fn(),
+        };
+
+        // Create use case with mock
+        useCase = new GetMigrationStatusUseCase({
+            processRepository: mockProcessRepository,
+        });
+    });
+
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    describe('constructor', () => {
+        it('should throw error if processRepository not provided', () => {
+            expect(() => {
+                new GetMigrationStatusUseCase({});
+            }).toThrow('processRepository dependency is required');
+        });
+    });
+
+    describe('execute', () => {
+        it('should return migration status for COMPLETED process', async () => {
+            const mockProcess = {
+                id: 'process-123',
+                type: 'DATABASE_MIGRATION',
+                state: 'COMPLETED',
+                context: {
+                    dbType: 'postgresql',
+                    stage: 'production',
+                    migrationCommand: 'migrate deploy',
+                },
+                results: {
+                    success: true,
+                    duration: '2341ms',
+                    timestamp: '2025-10-18T10:30:00Z',
+                },
+                createdAt: new Date('2025-10-18T10:29:55Z'),
+                updatedAt: new Date('2025-10-18T10:30:02Z'),
+            };
+
+            mockProcessRepository.findById.mockResolvedValue(mockProcess);
+
+            const result = await useCase.execute({ processId: 'process-123' });
+
+            expect(mockProcessRepository.findById).toHaveBeenCalledWith('process-123');
+            expect(result).toEqual({
+                processId: 'process-123',
+                type: 'DATABASE_MIGRATION',
+                state: 'COMPLETED',
+                context: mockProcess.context,
+                results: mockProcess.results,
+                createdAt: mockProcess.createdAt,
+                updatedAt: mockProcess.updatedAt,
+            });
+        });
+
+        it('should return migration status for RUNNING process', async () => {
+            const mockProcess = {
+                id: 'process-456',
+                type: 'DATABASE_MIGRATION',
+                state: 'RUNNING',
+                context: {
+                    dbType: 'mongodb',
+                    stage: 'dev',
+                    startedAt: '2025-10-18T10:30:00Z',
+                },
+                results: {},
+                createdAt: new Date('2025-10-18T10:29:55Z'),
+                updatedAt: new Date('2025-10-18T10:30:00Z'),
+            };
+
+            mockProcessRepository.findById.mockResolvedValue(mockProcess);
+
+            const result = await useCase.execute({ processId: 'process-456' });
+
+            expect(result.state).toBe('RUNNING');
+            expect(result.context.dbType).toBe('mongodb');
+        });
+
+        it('should return migration status for FAILED process', async () => {
+            const mockProcess = {
+                id: 'process-789',
+                type: 'DATABASE_MIGRATION',
+                state: 'FAILED',
+                context: {
+                    dbType: 'postgresql',
+                    stage: 'production',
+                    failedAt: '2025-10-18T10:30:00Z',
+                },
+                results: {
+                    error: 'Migration failed: syntax error',
+                    errorType: 'MigrationError',
+                },
+                createdAt: new Date('2025-10-18T10:29:55Z'),
+                updatedAt: new Date('2025-10-18T10:30:00Z'),
+            };
+
+            mockProcessRepository.findById.mockResolvedValue(mockProcess);
+
+            const result = await useCase.execute({ processId: 'process-789' });
+
+            expect(result.state).toBe('FAILED');
+            expect(result.results.error).toContain('Migration failed');
+        });
+
+        it('should handle empty context and results', async () => {
+            const mockProcess = {
+                id: 'process-999',
+                type: 'DATABASE_MIGRATION',
+                state: 'INITIALIZING',
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            };
+
+            mockProcessRepository.findById.mockResolvedValue(mockProcess);
+
+            const result = await useCase.execute({ processId: 'process-999' });
+
+            expect(result.context).toEqual({});
+            expect(result.results).toEqual({});
+        });
+
+        it('should throw NotFoundError if process does not exist', async () => {
+            mockProcessRepository.findById.mockResolvedValue(null);
+
+            await expect(
+                useCase.execute({ processId: 'nonexistent-123' })
+            ).rejects.toThrow(NotFoundError);
+
+            await expect(
+                useCase.execute({ processId: 'nonexistent-123' })
+            ).rejects.toThrow('Migration process not found: nonexistent-123');
+        });
+
+        it('should throw error if process is not a migration process', async () => {
+            const nonMigrationProcess = {
+                id: 'process-999',
+                type: 'CRM_SYNC', // Not a migration
+                state: 'RUNNING',
+                context: {},
+                results: {},
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            };
+
+            mockProcessRepository.findById.mockResolvedValue(nonMigrationProcess);
+
+            await expect(
+                useCase.execute({ processId: 'process-999' })
+            ).rejects.toThrow('Process process-999 is not a migration process (type: CRM_SYNC)');
+        });
+
+        it('should throw ValidationError if processId is missing', async () => {
+            await expect(
+                useCase.execute({})
+            ).rejects.toThrow(ValidationError);
+
+            await expect(
+                useCase.execute({})
+            ).rejects.toThrow('processId is required');
+        });
+
+        it('should throw ValidationError if processId is not a string', async () => {
+            await expect(
+                useCase.execute({ processId: 123 })
+            ).rejects.toThrow('processId must be a string');
+        });
+
+        it('should handle repository errors', async () => {
+            mockProcessRepository.findById.mockRejectedValue(new Error('Database connection failed'));
+
+            await expect(
+                useCase.execute({ processId: 'process-123' })
+            ).rejects.toThrow('Database connection failed');
+        });
+    });
+
+    describe('NotFoundError', () => {
+        it('should have correct properties', () => {
+            const error = new NotFoundError('test message');
+            expect(error.name).toBe('NotFoundError');
+            expect(error.message).toBe('test message');
+            expect(error.statusCode).toBe(404);
+            expect(error instanceof Error).toBe(true);
+        });
+    });
+
+    describe('ValidationError', () => {
+        it('should have correct name', () => {
+            const error = new ValidationError('test message');
+            expect(error.name).toBe('ValidationError');
+            expect(error.message).toBe('test message');
+            expect(error instanceof Error).toBe(true);
+        });
+    });
+});
+

package/database/use-cases/trigger-database-migration-use-case.js

@@ -0,0 +1,169 @@
+/**
+ * Trigger Database Migration Use Case
+ *
+ * Business logic for triggering async database migrations via SQS queue.
+ * Creates a Process record for tracking and sends migration job to queue.
+ *
+ * This use case follows the Frigg hexagonal architecture pattern where:
+ * - Routers (adapters) call use cases
+ * - Use cases contain business logic and orchestration
+ * - Use cases call repositories for data access
+ * - Use cases delegate infrastructure concerns (SQS) to utilities
+ *
+ * Flow:
+ * 1. Validate migration parameters
+ * 2. Create Process record (state: INITIALIZING)
+ * 3. Send message to SQS queue (fire-and-forget)
+ * 4. Return process info immediately (async pattern)
+ */
+
+const { QueuerUtil } = require('../../queues/queuer-util');
+
+class TriggerDatabaseMigrationUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {Object} dependencies.processRepository - Repository for process data access
+     * @param {Object} [dependencies.queuerUtil] - SQS utility (injectable for testing)
+     */
+    constructor({ processRepository, queuerUtil = QueuerUtil }) {
+        if (!processRepository) {
+            throw new Error('processRepository dependency is required');
+        }
+        this.processRepository = processRepository;
+        this.queuerUtil = queuerUtil;
+    }
+
+    /**
+     * Execute database migration trigger
+     *
+     * @param {Object} params
+     * @param {string} params.userId - User ID triggering the migration
+     * @param {string} params.dbType - Database type ('postgresql' or 'mongodb')
+     * @param {string} params.stage - Deployment stage (determines migration command)
+     * @returns {Promise<Object>} Process info { success, processId, state, statusUrl, message }
+     * @throws {ValidationError} If parameters are invalid
+     * @throws {Error} If process creation or queue send fails
+     */
+    async execute({ userId, dbType, stage }) {
+        // Validation
+        this._validateParams({ userId, dbType, stage });
+
+        // Create Process record for tracking
+        const migrationProcess = await this.processRepository.create({
+            userId,
+            integrationId: null, // System operation, not tied to integration
+            name: 'database-migration',
+            type: 'DATABASE_MIGRATION',
+            state: 'INITIALIZING',
+            context: {
+                dbType,
+                stage,
+                triggeredAt: new Date().toISOString(),
+            },
+            results: {},
+        });
+
+        console.log(`Created migration process: ${migrationProcess.id}`);
+
+        // Get queue URL from environment
+        const queueUrl = process.env.DB_MIGRATION_QUEUE_URL;
+        if (!queueUrl) {
+            throw new Error(
+                'DB_MIGRATION_QUEUE_URL environment variable is not set. ' +
+                'Cannot send migration to queue.'
+            );
+        }
+
+        // Send message to SQS queue (async fire-and-forget)
+        try {
+            await this.queuerUtil.send(
+                {
+                    processId: migrationProcess.id,
+                    dbType,
+                    stage,
+                },
+                queueUrl
+            );
+
+            console.log(`Sent migration job to queue for process: ${migrationProcess.id}`);
+        } catch (error) {
+            console.error(`Failed to send migration to queue:`, error);
+
+            // Update process state to FAILED
+            await this.processRepository.updateState(
+                migrationProcess.id,
+                'FAILED',
+                {
+                    error: 'Failed to queue migration job',
+                    errorDetails: error.message,
+                }
+            );
+
+            throw new Error(
+                `Failed to queue migration: ${error.message}`
+            );
+        }
+
+        // Return process info immediately (don't wait for migration completion)
+        return {
+            success: true,
+            processId: migrationProcess.id,
+            state: migrationProcess.state,
+            statusUrl: `/db-migrate/${migrationProcess.id}`,
+            message: 'Database migration queued successfully',
+        };
+    }
+
+    /**
+     * Validate execution parameters
+     * @private
+     */
+    _validateParams({ userId, dbType, stage }) {
+        if (!userId) {
+            throw new ValidationError('userId is required');
+        }
+
+        if (typeof userId !== 'string') {
+            throw new ValidationError('userId must be a string');
+        }
+
+        if (!dbType) {
+            throw new ValidationError('dbType is required');
+        }
+
+        if (typeof dbType !== 'string') {
+            throw new ValidationError('dbType must be a string');
+        }
+
+        const validDbTypes = ['postgresql', 'mongodb'];
+        if (!validDbTypes.includes(dbType)) {
+            throw new ValidationError(
+                `Invalid dbType: "${dbType}". Must be one of: ${validDbTypes.join(', ')}`
+            );
+        }
+
+        if (!stage) {
+            throw new ValidationError('stage is required');
+        }
+
+        if (typeof stage !== 'string') {
+            throw new ValidationError('stage must be a string');
+        }
+    }
+}
+
+/**
+ * Custom error for validation failures
+ */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+module.exports = {
+    TriggerDatabaseMigrationUseCase,
+    ValidationError,
+};
+