@friggframework/admin-scripts 2.0.0--canary.522.cbd3d5a.0 → 2.0.0--canary.517.35ee143.0

package/src/application/use-cases/__tests__/upsert-schedule-use-case.test.js

@@ -0,0 +1,201 @@
+const { UpsertScheduleUseCase } = require('../upsert-schedule-use-case');
+
+describe('UpsertScheduleUseCase', () => {
+    let useCase;
+    let mockCommands;
+    let mockSchedulerAdapter;
+    let mockScriptFactory;
+
+    beforeEach(() => {
+        mockCommands = {
+            upsertSchedule: jest.fn(),
+            updateScheduleExternalInfo: jest.fn(),
+        };
+
+        mockSchedulerAdapter = {
+            createSchedule: jest.fn(),
+            deleteSchedule: jest.fn(),
+        };
+
+        mockScriptFactory = {
+            has: jest.fn(),
+            get: jest.fn(),
+        };
+
+        useCase = new UpsertScheduleUseCase({
+            commands: mockCommands,
+            schedulerAdapter: mockSchedulerAdapter,
+            scriptFactory: mockScriptFactory,
+        });
+    });
+
+    describe('execute', () => {
+        it('should create schedule and provision external scheduler when enabled', async () => {
+            const savedSchedule = {
+                scriptName: 'test-script',
+                enabled: true,
+                cronExpression: '0 12 * * *',
+                timezone: 'UTC',
+            };
+
+            mockScriptFactory.has.mockReturnValue(true);
+            mockCommands.upsertSchedule.mockResolvedValue(savedSchedule);
+            mockSchedulerAdapter.createSchedule.mockResolvedValue({
+                scheduleArn: 'arn:aws:scheduler:us-east-1:123:schedule/test',
+                scheduleName: 'frigg-script-test-script',
+            });
+            mockCommands.updateScheduleExternalInfo.mockResolvedValue({
+                ...savedSchedule,
+                externalScheduleId: 'arn:aws:scheduler:us-east-1:123:schedule/test',
+            });
+
+            const result = await useCase.execute('test-script', {
+                enabled: true,
+                cronExpression: '0 12 * * *',
+                timezone: 'UTC',
+            });
+
+            expect(result.success).toBe(true);
+            expect(result.schedule.scriptName).toBe('test-script');
+            expect(mockSchedulerAdapter.createSchedule).toHaveBeenCalledWith({
+                scriptName: 'test-script',
+                cronExpression: '0 12 * * *',
+                timezone: 'UTC',
+            });
+            expect(mockCommands.updateScheduleExternalInfo).toHaveBeenCalled();
+        });
+
+        it('should default timezone to UTC', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+            mockCommands.upsertSchedule.mockResolvedValue({
+                scriptName: 'test-script',
+                enabled: true,
+                cronExpression: '0 12 * * *',
+                timezone: 'UTC',
+            });
+            mockSchedulerAdapter.createSchedule.mockResolvedValue({
+                scheduleArn: 'arn:test',
+                scheduleName: 'test',
+            });
+
+            await useCase.execute('test-script', {
+                enabled: true,
+                cronExpression: '0 12 * * *',
+            });
+
+            expect(mockSchedulerAdapter.createSchedule).toHaveBeenCalledWith({
+                scriptName: 'test-script',
+                cronExpression: '0 12 * * *',
+                timezone: 'UTC',
+            });
+        });
+
+        it('should delete external scheduler when disabling', async () => {
+            const existingSchedule = {
+                scriptName: 'test-script',
+                enabled: false,
+                cronExpression: null,
+                timezone: 'UTC',
+                externalScheduleId: 'arn:aws:scheduler:us-east-1:123:schedule/test',
+            };
+
+            mockScriptFactory.has.mockReturnValue(true);
+            mockCommands.upsertSchedule.mockResolvedValue(existingSchedule);
+            mockSchedulerAdapter.deleteSchedule.mockResolvedValue();
+            mockCommands.updateScheduleExternalInfo.mockResolvedValue({
+                ...existingSchedule,
+                externalScheduleId: null,
+            });
+
+            const result = await useCase.execute('test-script', {
+                enabled: false,
+            });
+
+            expect(result.success).toBe(true);
+            expect(mockSchedulerAdapter.deleteSchedule).toHaveBeenCalledWith('test-script');
+        });
+
+        it('should handle scheduler errors gracefully with warning', async () => {
+            const savedSchedule = {
+                scriptName: 'test-script',
+                enabled: true,
+                cronExpression: '0 12 * * *',
+                timezone: 'UTC',
+            };
+
+            mockScriptFactory.has.mockReturnValue(true);
+            mockCommands.upsertSchedule.mockResolvedValue(savedSchedule);
+            mockSchedulerAdapter.createSchedule.mockRejectedValue(
+                new Error('Scheduler API error')
+            );
+
+            const result = await useCase.execute('test-script', {
+                enabled: true,
+                cronExpression: '0 12 * * *',
+            });
+
+            // Should succeed with warning, not fail
+            expect(result.success).toBe(true);
+            expect(result.schedulerWarning).toBe('Scheduler API error');
+        });
+
+        it('should throw SCRIPT_NOT_FOUND error when script does not exist', async () => {
+            mockScriptFactory.has.mockReturnValue(false);
+
+            await expect(useCase.execute('non-existent', { enabled: true }))
+                .rejects.toThrow('Script "non-existent" not found');
+
+            try {
+                await useCase.execute('non-existent', { enabled: true });
+            } catch (error) {
+                expect(error.code).toBe('SCRIPT_NOT_FOUND');
+            }
+        });
+
+        it('should throw INVALID_INPUT error when enabled is not a boolean', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+
+            await expect(useCase.execute('test-script', { enabled: 'yes' }))
+                .rejects.toThrow('enabled must be a boolean');
+
+            try {
+                await useCase.execute('test-script', { enabled: 'yes' });
+            } catch (error) {
+                expect(error.code).toBe('INVALID_INPUT');
+            }
+        });
+
+        it('should throw INVALID_INPUT error when enabled without cronExpression', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+
+            await expect(useCase.execute('test-script', { enabled: true }))
+                .rejects.toThrow('cronExpression is required when enabled is true');
+
+            try {
+                await useCase.execute('test-script', { enabled: true });
+            } catch (error) {
+                expect(error.code).toBe('INVALID_INPUT');
+            }
+        });
+
+        it('should not require cronExpression when disabled', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+            mockCommands.upsertSchedule.mockResolvedValue({
+                scriptName: 'test-script',
+                enabled: false,
+                cronExpression: null,
+                timezone: 'UTC',
+            });
+
+            const result = await useCase.execute('test-script', { enabled: false });
+
+            expect(result.success).toBe(true);
+            expect(mockCommands.upsertSchedule).toHaveBeenCalledWith({
+                scriptName: 'test-script',
+                enabled: false,
+                cronExpression: null,
+                timezone: 'UTC',
+            });
+        });
+    });
+});

package/src/application/use-cases/delete-schedule-use-case.js

@@ -0,0 +1,108 @@
+/**
+ * Delete Schedule Use Case
+ *
+ * Application Layer - Hexagonal Architecture
+ *
+ * Deletes a schedule override and cleans up external scheduler resources.
+ * Returns the effective schedule after deletion (may fall back to definition).
+ */
+class DeleteScheduleUseCase {
+    constructor({ commands, schedulerAdapter, scriptFactory }) {
+        this.commands = commands;
+        this.schedulerAdapter = schedulerAdapter;
+        this.scriptFactory = scriptFactory;
+    }
+
+    /**
+     * Delete a schedule override
+     * @param {string} scriptName - Name of the script
+     * @returns {Promise<{success: boolean, deletedCount: number, message: string, effectiveSchedule: Object, schedulerWarning?: string}>}
+     */
+    async execute(scriptName) {
+        this._validateScriptExists(scriptName);
+
+        // Delete from database
+        const deleteResult = await this.commands.deleteSchedule(scriptName);
+
+        // Cleanup external scheduler if needed
+        const schedulerWarning = await this._cleanupExternalScheduler(
+            scriptName,
+            deleteResult.deleted?.externalScheduleId
+        );
+
+        // Determine effective schedule after deletion
+        const effectiveSchedule = this._getEffectiveScheduleAfterDeletion(scriptName);
+
+        return {
+            success: true,
+            deletedCount: deleteResult.deletedCount,
+            message: deleteResult.deletedCount > 0
+                ? 'Schedule override removed'
+                : 'No schedule override found',
+            effectiveSchedule,
+            ...(schedulerWarning && { schedulerWarning }),
+        };
+    }
+
+    /**
+     * @private
+     */
+    _validateScriptExists(scriptName) {
+        if (!this.scriptFactory.has(scriptName)) {
+            const error = new Error(`Script "${scriptName}" not found`);
+            error.code = 'SCRIPT_NOT_FOUND';
+            throw error;
+        }
+    }
+
+    /**
+     * Get the definition schedule from a script class
+     * @private
+     */
+    _getDefinitionSchedule(scriptName) {
+        const scriptClass = this.scriptFactory.get(scriptName);
+        return scriptClass.Definition?.schedule || null;
+    }
+
+    /**
+     * Determine effective schedule after deletion
+     * @private
+     */
+    _getEffectiveScheduleAfterDeletion(scriptName) {
+        const definitionSchedule = this._getDefinitionSchedule(scriptName);
+
+        if (definitionSchedule?.enabled) {
+            return {
+                source: 'definition',
+                enabled: definitionSchedule.enabled,
+                cronExpression: definitionSchedule.cronExpression,
+                timezone: definitionSchedule.timezone || 'UTC',
+            };
+        }
+
+        return {
+            source: 'none',
+            enabled: false,
+        };
+    }
+
+    /**
+     * Cleanup external scheduler resources
+     * @private
+     */
+    async _cleanupExternalScheduler(scriptName, externalScheduleId) {
+        if (!externalScheduleId) {
+            return null;
+        }
+
+        try {
+            await this.schedulerAdapter.deleteSchedule(scriptName);
+            return null;
+        } catch (error) {
+            // Non-fatal: DB is cleaned up, external scheduler can be retried
+            return error.message;
+        }
+    }
+}
+
+module.exports = { DeleteScheduleUseCase };

package/src/application/use-cases/get-effective-schedule-use-case.js

@@ -0,0 +1,78 @@
+/**
+ * Get Effective Schedule Use Case
+ *
+ * Application Layer - Hexagonal Architecture
+ *
+ * Resolves the effective schedule for a script following priority:
+ * 1. Database override (runtime configuration)
+ * 2. Definition default (code-defined schedule)
+ * 3. None (manual execution only)
+ */
+class GetEffectiveScheduleUseCase {
+    constructor({ commands, scriptFactory }) {
+        this.commands = commands;
+        this.scriptFactory = scriptFactory;
+    }
+
+    /**
+     * Get effective schedule for a script
+     * @param {string} scriptName - Name of the script
+     * @returns {Promise<{source: 'database'|'definition'|'none', schedule: Object}>}
+     */
+    async execute(scriptName) {
+        this._validateScriptExists(scriptName);
+
+        // Priority 1: Database override
+        const dbSchedule = await this.commands.getScheduleByScriptName(scriptName);
+        if (dbSchedule) {
+            return {
+                source: 'database',
+                schedule: dbSchedule,
+            };
+        }
+
+        // Priority 2: Definition default
+        const definitionSchedule = this._getDefinitionSchedule(scriptName);
+        if (definitionSchedule?.enabled) {
+            return {
+                source: 'definition',
+                schedule: {
+                    scriptName,
+                    enabled: definitionSchedule.enabled,
+                    cronExpression: definitionSchedule.cronExpression,
+                    timezone: definitionSchedule.timezone || 'UTC',
+                },
+            };
+        }
+
+        // Priority 3: No schedule
+        return {
+            source: 'none',
+            schedule: {
+                scriptName,
+                enabled: false,
+            },
+        };
+    }
+
+    /**
+     * @private
+     */
+    _validateScriptExists(scriptName) {
+        if (!this.scriptFactory.has(scriptName)) {
+            const error = new Error(`Script "${scriptName}" not found`);
+            error.code = 'SCRIPT_NOT_FOUND';
+            throw error;
+        }
+    }
+
+    /**
+     * @private
+     */
+    _getDefinitionSchedule(scriptName) {
+        const scriptClass = this.scriptFactory.get(scriptName);
+        return scriptClass.Definition?.schedule || null;
+    }
+}
+
+module.exports = { GetEffectiveScheduleUseCase };

package/src/application/use-cases/index.js

@@ -0,0 +1,18 @@
+/**
+ * Schedule Management Use Cases
+ *
+ * Separated by Single Responsibility Principle:
+ * - GetEffectiveScheduleUseCase: Read schedule with priority resolution
+ * - UpsertScheduleUseCase: Create/update schedule with scheduler sync
+ * - DeleteScheduleUseCase: Delete schedule with scheduler cleanup
+ */
+
+const { GetEffectiveScheduleUseCase } = require('./get-effective-schedule-use-case');
+const { UpsertScheduleUseCase } = require('./upsert-schedule-use-case');
+const { DeleteScheduleUseCase } = require('./delete-schedule-use-case');
+
+module.exports = {
+    GetEffectiveScheduleUseCase,
+    UpsertScheduleUseCase,
+    DeleteScheduleUseCase,
+};

package/src/application/use-cases/upsert-schedule-use-case.js

@@ -0,0 +1,127 @@
+/**
+ * Upsert Schedule Use Case
+ *
+ * Application Layer - Hexagonal Architecture
+ *
+ * Creates or updates a schedule override with external scheduler provisioning.
+ * Abstracts scheduler provider (AWS EventBridge, etc.) behind schedulerAdapter.
+ */
+class UpsertScheduleUseCase {
+    constructor({ commands, schedulerAdapter, scriptFactory }) {
+        this.commands = commands;
+        this.schedulerAdapter = schedulerAdapter;
+        this.scriptFactory = scriptFactory;
+    }
+
+    /**
+     * Create or update a schedule
+     * @param {string} scriptName - Name of the script
+     * @param {Object} input - Schedule configuration
+     * @param {boolean} input.enabled - Whether schedule is enabled
+     * @param {string} [input.cronExpression] - Cron expression (required if enabled)
+     * @param {string} [input.timezone] - Timezone (defaults to UTC)
+     * @returns {Promise<{success: boolean, schedule: Object, schedulerWarning?: string}>}
+     */
+    async execute(scriptName, { enabled, cronExpression, timezone }) {
+        this._validateScriptExists(scriptName);
+        this._validateInput(enabled, cronExpression);
+
+        // Save to database
+        const schedule = await this.commands.upsertSchedule({
+            scriptName,
+            enabled,
+            cronExpression: cronExpression || null,
+            timezone: timezone || 'UTC',
+        });
+
+        // Sync with external scheduler (AWS EventBridge, etc.)
+        const schedulerResult = await this._syncExternalScheduler(
+            scriptName,
+            enabled,
+            cronExpression,
+            timezone,
+            schedule.externalScheduleId
+        );
+
+        return {
+            success: true,
+            schedule: {
+                ...schedule,
+                externalScheduleId: schedulerResult.externalScheduleId || schedule.externalScheduleId,
+                externalScheduleName: schedulerResult.externalScheduleName || schedule.externalScheduleName,
+            },
+            ...(schedulerResult.warning && { schedulerWarning: schedulerResult.warning }),
+        };
+    }
+
+    /**
+     * @private
+     */
+    _validateScriptExists(scriptName) {
+        if (!this.scriptFactory.has(scriptName)) {
+            const error = new Error(`Script "${scriptName}" not found`);
+            error.code = 'SCRIPT_NOT_FOUND';
+            throw error;
+        }
+    }
+
+    /**
+     * @private
+     */
+    _validateInput(enabled, cronExpression) {
+        if (typeof enabled !== 'boolean') {
+            const error = new Error('enabled must be a boolean');
+            error.code = 'INVALID_INPUT';
+            throw error;
+        }
+
+        if (enabled && !cronExpression) {
+            const error = new Error('cronExpression is required when enabled is true');
+            error.code = 'INVALID_INPUT';
+            throw error;
+        }
+    }
+
+    /**
+     * Sync with external scheduler service
+     * Abstracts AWS EventBridge or other scheduler providers
+     * @private
+     */
+    async _syncExternalScheduler(scriptName, enabled, cronExpression, timezone, existingId) {
+        const result = { externalScheduleId: null, externalScheduleName: null, warning: null };
+
+        try {
+            if (enabled && cronExpression) {
+                // Create/update external schedule
+                const schedulerInfo = await this.schedulerAdapter.createSchedule({
+                    scriptName,
+                    cronExpression,
+                    timezone: timezone || 'UTC',
+                });
+
+                if (schedulerInfo?.scheduleArn) {
+                    await this.commands.updateScheduleExternalInfo(scriptName, {
+                        externalScheduleId: schedulerInfo.scheduleArn,
+                        externalScheduleName: schedulerInfo.scheduleName,
+                    });
+                    result.externalScheduleId = schedulerInfo.scheduleArn;
+                    result.externalScheduleName = schedulerInfo.scheduleName;
+                }
+            } else if (!enabled && existingId) {
+                // Delete external schedule
+                await this.schedulerAdapter.deleteSchedule(scriptName);
+                await this.commands.updateScheduleExternalInfo(scriptName, {
+                    externalScheduleId: null,
+                    externalScheduleName: null,
+                });
+            }
+        } catch (error) {
+            // Non-fatal: DB schedule is saved, external scheduler can be retried
+            result.warning = error.message;
+        }
+
+        return result;
+    }
+}
+
+module.exports = { UpsertScheduleUseCase };

package/src/builtins/__tests__/integration-health-check.test.js

@@ -6,7 +6,7 @@ describe('IntegrationHealthCheckScript', () => {
             expect(IntegrationHealthCheckScript.Definition.name).toBe('integration-health-check');
             expect(IntegrationHealthCheckScript.Definition.version).toBe('1.0.0');
             expect(IntegrationHealthCheckScript.Definition.source).toBe('BUILTIN');
-            expect(IntegrationHealthCheckScript.Definition.config.requiresIntegrationFactory).toBe(true);
+            expect(IntegrationHealthCheckScript.Definition.config.requireIntegrationInstance).toBe(true);
         });
 
         it('should have valid input schema', () => {

package/src/builtins/__tests__/oauth-token-refresh.test.js

@@ -6,7 +6,7 @@ describe('OAuthTokenRefreshScript', () => {
             expect(OAuthTokenRefreshScript.Definition.name).toBe('oauth-token-refresh');
             expect(OAuthTokenRefreshScript.Definition.version).toBe('1.0.0');
             expect(OAuthTokenRefreshScript.Definition.source).toBe('BUILTIN');
-            expect(OAuthTokenRefreshScript.Definition.config.requiresIntegrationFactory).toBe(true);
+            expect(OAuthTokenRefreshScript.Definition.config.requireIntegrationInstance).toBe(true);
         });
 
         it('should have valid input schema', () => {

package/src/builtins/integration-health-check.js

@@ -54,7 +54,7 @@ class IntegrationHealthCheckScript extends AdminScriptBase {
         config: {
             timeout: 900000, // 15 minutes
             maxRetries: 0,
-            requiresIntegrationFactory: true,
+            requireIntegrationInstance: true,
         },
 
         schedule: {

package/src/builtins/oauth-token-refresh.js

@@ -47,7 +47,7 @@ class OAuthTokenRefreshScript extends AdminScriptBase {
         config: {
             timeout: 600000, // 10 minutes
             maxRetries: 1,
-            requiresIntegrationFactory: true, // Needs to call external APIs
+            requireIntegrationInstance: true, // Needs to call external APIs
         },
 
         display: {