@friggframework/admin-scripts 2.0.0--canary.517.300ded3.0 → 2.0.0--canary.517.35ee143.0

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: {

package/src/infrastructure/__tests__/admin-script-router.test.js

@@ -99,7 +99,7 @@ describe('Admin Script Router', () => {
                 version: '1.0.0',
                 description: 'Test script',
                 category: 'test',
-                requiresIntegrationFactory: false,
+                requireIntegrationInstance: false,
                 schedule: null,
             });
         });
@@ -293,8 +293,8 @@ describe('Admin Script Router', () => {
                 timezone: 'America/New_York',
                 lastTriggeredAt: new Date('2025-01-01T09:00:00Z'),
                 nextTriggerAt: new Date('2025-01-02T09:00:00Z'),
-                awsScheduleArn: 'arn:aws:events:us-east-1:123456789012:rule/test',
-                awsScheduleName: 'test-script-schedule',
+                externalScheduleId: 'arn:aws:events:us-east-1:123456789012:rule/test',
+                externalScheduleName: 'test-script-schedule',
                 createdAt: new Date('2025-01-01T00:00:00Z'),
                 updatedAt: new Date('2025-01-01T00:00:00Z'),
             };
@@ -470,7 +470,7 @@ describe('Admin Script Router', () => {
             };
 
             mockCommands.upsertSchedule = jest.fn().mockResolvedValue(newSchedule);
-            mockCommands.updateScheduleAwsInfo = jest.fn().mockResolvedValue(newSchedule);
+            mockCommands.updateScheduleExternalInfo = jest.fn().mockResolvedValue(newSchedule);
             mockSchedulerAdapter.createSchedule.mockResolvedValue({
                 scheduleArn: 'arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script',
                 scheduleName: 'frigg-script-test-script',
@@ -490,11 +490,11 @@ describe('Admin Script Router', () => {
                 cronExpression: '0 12 * * *',
                 timezone: 'America/Los_Angeles',
             });
-            expect(mockCommands.updateScheduleAwsInfo).toHaveBeenCalledWith('test-script', {
-                awsScheduleArn: 'arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script',
-                awsScheduleName: 'frigg-script-test-script',
+            expect(mockCommands.updateScheduleExternalInfo).toHaveBeenCalledWith('test-script', {
+                externalScheduleId: 'arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script',
+                externalScheduleName: 'frigg-script-test-script',
             });
-            expect(response.body.schedule.awsScheduleArn).toBe('arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script');
+            expect(response.body.schedule.externalScheduleId).toBe('arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script');
         });
 
         it('should delete EventBridge schedule when disabling existing schedule', async () => {
@@ -503,14 +503,14 @@ describe('Admin Script Router', () => {
                 enabled: false,
                 cronExpression: null,
                 timezone: 'UTC',
-                awsScheduleArn: 'arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script',
-                awsScheduleName: 'frigg-script-test-script',
+                externalScheduleId: 'arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script',
+                externalScheduleName: 'frigg-script-test-script',
                 createdAt: new Date(),
                 updatedAt: new Date(),
             };
 
             mockCommands.upsertSchedule = jest.fn().mockResolvedValue(existingSchedule);
-            mockCommands.updateScheduleAwsInfo = jest.fn().mockResolvedValue(existingSchedule);
+            mockCommands.updateScheduleExternalInfo = jest.fn().mockResolvedValue(existingSchedule);
             mockSchedulerAdapter.deleteSchedule.mockResolvedValue();
 
             const response = await request(app)
@@ -521,9 +521,9 @@ describe('Admin Script Router', () => {
 
             expect(response.status).toBe(200);
             expect(mockSchedulerAdapter.deleteSchedule).toHaveBeenCalledWith('test-script');
-            expect(mockCommands.updateScheduleAwsInfo).toHaveBeenCalledWith('test-script', {
-                awsScheduleArn: null,
-                awsScheduleName: null,
+            expect(mockCommands.updateScheduleExternalInfo).toHaveBeenCalledWith('test-script', {
+                externalScheduleId: null,
+                externalScheduleName: null,
             });
         });
 
@@ -632,7 +632,7 @@ describe('Admin Script Router', () => {
             expect(response.body.code).toBe('SCRIPT_NOT_FOUND');
         });
 
-        it('should delete EventBridge schedule when AWS rule exists', async () => {
+        it('should delete EventBridge schedule when external rule exists', async () => {
             mockCommands.deleteSchedule = jest.fn().mockResolvedValue({
                 acknowledged: true,
                 deletedCount: 1,
@@ -640,8 +640,8 @@ describe('Admin Script Router', () => {
                     scriptName: 'test-script',
                     enabled: true,
                     cronExpression: '0 12 * * *',
-                    awsScheduleArn: 'arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script',
-                    awsScheduleName: 'frigg-script-test-script',
+                    externalScheduleId: 'arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script',
+                    externalScheduleName: 'frigg-script-test-script',
                 },
             });
             mockSchedulerAdapter.deleteSchedule.mockResolvedValue();
@@ -654,7 +654,7 @@ describe('Admin Script Router', () => {
             expect(mockSchedulerAdapter.deleteSchedule).toHaveBeenCalledWith('test-script');
         });
 
-        it('should not call scheduler when no AWS rule exists', async () => {
+        it('should not call scheduler when no external rule exists', async () => {
             mockCommands.deleteSchedule = jest.fn().mockResolvedValue({
                 acknowledged: true,
                 deletedCount: 1,
@@ -662,7 +662,7 @@ describe('Admin Script Router', () => {
                     scriptName: 'test-script',
                     enabled: true,
                     cronExpression: '0 12 * * *',
-                    // No awsScheduleArn
+                    // No externalScheduleId
                 },
             });
 
@@ -682,10 +682,10 @@ describe('Admin Script Router', () => {
                     scriptName: 'test-script',
                     enabled: true,
                     cronExpression: '0 12 * * *',
-                    awsScheduleArn: 'arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script',
+                    externalScheduleId: 'arn:aws:scheduler:us-east-1:123456789012:schedule/frigg-admin-scripts/frigg-script-test-script',
                 },
             });
-            mockSchedulerAdapter.deleteSchedule.mockRejectedValue(new Error('AWS Scheduler delete failed'));
+            mockSchedulerAdapter.deleteSchedule.mockRejectedValue(new Error('Scheduler delete failed'));
 
             const response = await request(app).delete(
                 '/admin/scripts/test-script/schedule'
@@ -694,7 +694,7 @@ describe('Admin Script Router', () => {
             // Request should succeed despite scheduler error
             expect(response.status).toBe(200);
             expect(response.body.success).toBe(true);
-            expect(response.body.schedulerWarning).toBe('AWS Scheduler delete failed');
+            expect(response.body.schedulerWarning).toBe('Scheduler delete failed');
         });
     });
 });

package/src/infrastructure/admin-script-router.js

@@ -6,7 +6,11 @@ const { createScriptRunner } = require('../application/script-runner');
 const { createAdminScriptCommands } = require('@friggframework/core/application/commands/admin-script-commands');
 const { QueuerUtil } = require('@friggframework/core/queues');
 const { createSchedulerAdapter } = require('../adapters/scheduler-adapter-factory');
-const { ScheduleManagementUseCase } = require('../application/schedule-management-use-case');
+const {
+    GetEffectiveScheduleUseCase,
+    UpsertScheduleUseCase,
+    DeleteScheduleUseCase,
+} = require('../application/use-cases');
 
 const router = express.Router();
 
@@ -14,15 +18,19 @@ const router = express.Router();
 router.use(validateAdminApiKey);
 
 /**
- * Create ScheduleManagementUseCase instance
+ * Create schedule use case instances
  * @private
  */
-function createScheduleManagementUseCase() {
-    return new ScheduleManagementUseCase({
-        commands: createAdminScriptCommands(),
-        schedulerAdapter: createSchedulerAdapter(),
-        scriptFactory: getScriptFactory(),
-    });
+function createScheduleUseCases() {
+    const commands = createAdminScriptCommands();
+    const schedulerAdapter = createSchedulerAdapter();
+    const scriptFactory = getScriptFactory();
+
+    return {
+        getEffectiveSchedule: new GetEffectiveScheduleUseCase({ commands, scriptFactory }),
+        upsertSchedule: new UpsertScheduleUseCase({ commands, schedulerAdapter, scriptFactory }),
+        deleteSchedule: new DeleteScheduleUseCase({ commands, schedulerAdapter, scriptFactory }),
+    };
 }
 
 /**
@@ -40,8 +48,8 @@ router.get('/scripts', async (req, res) => {
                 version: s.definition.version,
                 description: s.definition.description,
                 category: s.definition.display?.category || 'custom',
-                requiresIntegrationFactory:
-                    s.definition.config?.requiresIntegrationFactory || false,
+                requireIntegrationInstance:
+                    s.definition.config?.requireIntegrationInstance || false,
                 schedule: s.definition.schedule || null,
             })),
         });
@@ -211,9 +219,9 @@ router.get('/scripts/:scriptName/executions', async (req, res) => {
 router.get('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
-        const useCase = createScheduleManagementUseCase();
+        const { getEffectiveSchedule } = createScheduleUseCases();
 
-        const result = await useCase.getEffectiveSchedule(scriptName);
+        const result = await getEffectiveSchedule.execute(scriptName);
 
         res.json({
             source: result.source,
@@ -240,9 +248,9 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
         const { enabled, cronExpression, timezone } = req.body;
-        const useCase = createScheduleManagementUseCase();
+        const { upsertSchedule } = createScheduleUseCases();
 
-        const result = await useCase.upsertSchedule(scriptName, {
+        const result = await upsertSchedule.execute(scriptName, {
             enabled,
             cronExpression,
             timezone,
@@ -281,9 +289,9 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
 router.delete('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
-        const useCase = createScheduleManagementUseCase();
+        const { deleteSchedule } = createScheduleUseCases();
 
-        const result = await useCase.deleteSchedule(scriptName);
+        const result = await deleteSchedule.execute(scriptName);
 
         res.json(result);
     } catch (error) {