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

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@friggframework/admin-scripts",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.517.300ded3.0",
+    "version": "2.0.0--canary.517.35ee143.0",
     "description": "Admin Script Runner for Frigg - Execute maintenance and operational scripts in hosted environments",
     "dependencies": {
         "@aws-sdk/client-scheduler": "^3.588.0",
-        "@friggframework/core": "2.0.0--canary.517.300ded3.0",
+        "@friggframework/core": "2.0.0--canary.517.35ee143.0",
         "bcryptjs": "^2.4.3",
         "express": "^4.18.2",
         "lodash": "4.17.21",
@@ -13,13 +13,12 @@
         "uuid": "^9.0.1"
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.517.300ded3.0",
-        "@friggframework/prettier-config": "2.0.0--canary.517.300ded3.0",
-        "@friggframework/test": "2.0.0--canary.517.300ded3.0",
+        "@friggframework/eslint-config": "2.0.0--canary.517.35ee143.0",
+        "@friggframework/prettier-config": "2.0.0--canary.517.35ee143.0",
+        "@friggframework/test": "2.0.0--canary.517.35ee143.0",
         "eslint": "^8.22.0",
         "jest": "^29.7.0",
         "prettier": "^2.7.1",
-        "sinon": "^16.1.1",
         "supertest": "^7.1.4"
     },
     "scripts": {
@@ -47,5 +46,5 @@
         "maintenance",
         "operations"
     ],
-    "gitHead": "300ded3ac35558075a081104b4b362b85cf0756f"
+    "gitHead": "35ee143ec0654d0935aee59bf62b882f5f27d8b7"
 }

package/src/application/__tests__/admin-frigg-commands.test.js

@@ -341,7 +341,7 @@ describe('AdminFriggCommands', () => {
 
             await expect(commands.instantiate('int_123')).rejects.toThrow(
                 'instantiate() requires integrationFactory. ' +
-                'Set Definition.config.requiresIntegrationFactory = true'
+                'Set Definition.config.requireIntegrationInstance = true'
             );
         });
 

package/src/application/__tests__/admin-script-base.test.js

@@ -28,7 +28,7 @@ describe('AdminScriptBase', () => {
                     config: {
                         timeout: 600000,
                         maxRetries: 3,
-                        requiresIntegrationFactory: true,
+                        requireIntegrationInstance: true,
                     },
                     display: {
                         label: 'Test Script',
@@ -236,7 +236,7 @@ describe('AdminScriptBase', () => {
                     version: '1.0.0',
                     description: 'My test script',
                     config: {
-                        requiresIntegrationFactory: true,
+                        requireIntegrationInstance: true,
                     },
                 };
 

package/src/application/__tests__/script-runner.test.js

@@ -23,7 +23,7 @@ describe('ScriptRunner', () => {
             config: {
                 timeout: 300000,
                 maxRetries: 0,
-                requiresIntegrationFactory: false,
+                requireIntegrationInstance: false,
             },
         };
 
@@ -146,7 +146,7 @@ describe('ScriptRunner', () => {
                     version: '1.0.0',
                     description: 'Integration script',
                     config: {
-                        requiresIntegrationFactory: true,
+                        requireIntegrationInstance: true,
                     },
                 };
 

package/src/application/admin-frigg-commands.js

@@ -142,7 +142,7 @@ class AdminFriggCommands {
         if (!this.integrationFactory) {
             throw new Error(
                 'instantiate() requires integrationFactory. ' +
-                'Set Definition.config.requiresIntegrationFactory = true'
+                'Set Definition.config.requireIntegrationInstance = true'
             );
         }
         return this.integrationFactory.getInstanceFromIntegrationId({

package/src/application/admin-script-base.js

@@ -50,7 +50,7 @@ class AdminScriptBase {
         config: {
             timeout: 300000, // Default 5 min (ms)
             maxRetries: 0,
-            requiresIntegrationFactory: false, // Hint: does script need to instantiate integrations?
+            requireIntegrationInstance: false, // Hint: does script need to instantiate integrations?
         },
 
         display: {

package/src/application/script-runner.js

@@ -27,7 +27,9 @@ class ScriptRunner {
      * @param {string} options.trigger - 'MANUAL' | 'SCHEDULED' | 'QUEUE'
      * @param {string} options.mode - 'sync' | 'async'
      * @param {Object} options.audit - Audit info { apiKeyName, apiKeyLast4, ipAddress }
-     * @param {string} options.executionId - Reuse existing execution ID
+     * @param {string} options.executionId - Reuse existing AdminProcess record ID (NOT the Lambda execution ID).
+     *   This is the database ID from the AdminProcess collection/table that tracks script executions.
+     *   Pass this when resuming a queued execution to continue using the same execution record.
      * @param {boolean} options.dryRun - Dry-run mode: validate and preview without executing
      */
     async execute(scriptName, params = {}, options = {}) {
@@ -38,7 +40,7 @@ class ScriptRunner {
         const definition = scriptClass.Definition;
 
         // Validate integrationFactory requirement
-        if (definition.config?.requiresIntegrationFactory && !this.integrationFactory) {
+        if (definition.config?.requireIntegrationInstance && !this.integrationFactory) {
             throw new Error(
                 `Script "${scriptName}" requires integrationFactory but none was provided`
             );
@@ -157,7 +159,7 @@ class ScriptRunner {
                     name: definition.name,
                     version: definition.version,
                     description: definition.description,
-                    requiresIntegrationFactory: definition.config?.requiresIntegrationFactory || false,
+                    requireIntegrationInstance: definition.config?.requireIntegrationInstance || false,
                 },
                 input: params,
                 inputSchema: definition.inputSchema || null,

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

@@ -0,0 +1,168 @@
+const { DeleteScheduleUseCase } = require('../delete-schedule-use-case');
+
+describe('DeleteScheduleUseCase', () => {
+    let useCase;
+    let mockCommands;
+    let mockSchedulerAdapter;
+    let mockScriptFactory;
+
+    beforeEach(() => {
+        mockCommands = {
+            deleteSchedule: jest.fn(),
+        };
+
+        mockSchedulerAdapter = {
+            deleteSchedule: jest.fn(),
+        };
+
+        mockScriptFactory = {
+            has: jest.fn(),
+            get: jest.fn(),
+        };
+
+        useCase = new DeleteScheduleUseCase({
+            commands: mockCommands,
+            schedulerAdapter: mockSchedulerAdapter,
+            scriptFactory: mockScriptFactory,
+        });
+    });
+
+    describe('execute', () => {
+        it('should delete schedule and cleanup external scheduler', async () => {
+            const deletedSchedule = {
+                scriptName: 'test-script',
+                externalScheduleId: 'arn:aws:scheduler:us-east-1:123:schedule/test',
+            };
+
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({ Definition: {} });
+            mockCommands.deleteSchedule.mockResolvedValue({
+                deletedCount: 1,
+                deleted: deletedSchedule,
+            });
+            mockSchedulerAdapter.deleteSchedule.mockResolvedValue();
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.success).toBe(true);
+            expect(result.deletedCount).toBe(1);
+            expect(result.message).toBe('Schedule override removed');
+            expect(mockSchedulerAdapter.deleteSchedule).toHaveBeenCalledWith('test-script');
+        });
+
+        it('should not call scheduler when no external rule exists', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({ Definition: {} });
+            mockCommands.deleteSchedule.mockResolvedValue({
+                deletedCount: 1,
+                deleted: { scriptName: 'test-script' }, // No externalScheduleId
+            });
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.success).toBe(true);
+            expect(mockSchedulerAdapter.deleteSchedule).not.toHaveBeenCalled();
+        });
+
+        it('should handle scheduler delete errors gracefully with warning', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({ Definition: {} });
+            mockCommands.deleteSchedule.mockResolvedValue({
+                deletedCount: 1,
+                deleted: {
+                    scriptName: 'test-script',
+                    externalScheduleId: 'arn:aws:scheduler:us-east-1:123:schedule/test',
+                },
+            });
+            mockSchedulerAdapter.deleteSchedule.mockRejectedValue(
+                new Error('Scheduler delete failed')
+            );
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.success).toBe(true);
+            expect(result.schedulerWarning).toBe('Scheduler delete failed');
+        });
+
+        it('should return definition schedule as effective after deletion', async () => {
+            const definitionSchedule = {
+                enabled: true,
+                cronExpression: '0 6 * * *',
+                timezone: 'America/Los_Angeles',
+            };
+
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({
+                Definition: { schedule: definitionSchedule },
+            });
+            mockCommands.deleteSchedule.mockResolvedValue({
+                deletedCount: 1,
+                deleted: { scriptName: 'test-script' },
+            });
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.effectiveSchedule.source).toBe('definition');
+            expect(result.effectiveSchedule.enabled).toBe(true);
+            expect(result.effectiveSchedule.cronExpression).toBe('0 6 * * *');
+            expect(result.effectiveSchedule.timezone).toBe('America/Los_Angeles');
+        });
+
+        it('should default timezone to UTC when not in definition', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({
+                Definition: { schedule: { enabled: true, cronExpression: '0 6 * * *' } },
+            });
+            mockCommands.deleteSchedule.mockResolvedValue({
+                deletedCount: 1,
+                deleted: { scriptName: 'test-script' },
+            });
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.effectiveSchedule.timezone).toBe('UTC');
+        });
+
+        it('should return none as effective when no definition schedule', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({ Definition: {} });
+            mockCommands.deleteSchedule.mockResolvedValue({
+                deletedCount: 1,
+                deleted: { scriptName: 'test-script' },
+            });
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.effectiveSchedule.source).toBe('none');
+            expect(result.effectiveSchedule.enabled).toBe(false);
+        });
+
+        it('should return correct message when no schedule found', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({ Definition: {} });
+            mockCommands.deleteSchedule.mockResolvedValue({
+                deletedCount: 0,
+                deleted: null,
+            });
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.success).toBe(true);
+            expect(result.deletedCount).toBe(0);
+            expect(result.message).toBe('No schedule override found');
+        });
+
+        it('should throw SCRIPT_NOT_FOUND error when script does not exist', async () => {
+            mockScriptFactory.has.mockReturnValue(false);
+
+            await expect(useCase.execute('non-existent'))
+                .rejects.toThrow('Script "non-existent" not found');
+
+            try {
+                await useCase.execute('non-existent');
+            } catch (error) {
+                expect(error.code).toBe('SCRIPT_NOT_FOUND');
+            }
+        });
+    });
+});

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

@@ -0,0 +1,114 @@
+const { GetEffectiveScheduleUseCase } = require('../get-effective-schedule-use-case');
+
+describe('GetEffectiveScheduleUseCase', () => {
+    let useCase;
+    let mockCommands;
+    let mockScriptFactory;
+
+    beforeEach(() => {
+        mockCommands = {
+            getScheduleByScriptName: jest.fn(),
+        };
+
+        mockScriptFactory = {
+            has: jest.fn(),
+            get: jest.fn(),
+        };
+
+        useCase = new GetEffectiveScheduleUseCase({
+            commands: mockCommands,
+            scriptFactory: mockScriptFactory,
+        });
+    });
+
+    describe('execute', () => {
+        it('should return database schedule when override exists', async () => {
+            const dbSchedule = {
+                scriptName: 'test-script',
+                enabled: true,
+                cronExpression: '0 9 * * *',
+                timezone: 'UTC',
+            };
+
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({ Definition: {} });
+            mockCommands.getScheduleByScriptName.mockResolvedValue(dbSchedule);
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.source).toBe('database');
+            expect(result.schedule).toEqual(dbSchedule);
+        });
+
+        it('should return definition schedule when no database override', async () => {
+            const definitionSchedule = {
+                enabled: true,
+                cronExpression: '0 12 * * *',
+                timezone: 'America/New_York',
+            };
+
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({
+                Definition: { schedule: definitionSchedule },
+            });
+            mockCommands.getScheduleByScriptName.mockResolvedValue(null);
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.source).toBe('definition');
+            expect(result.schedule.enabled).toBe(true);
+            expect(result.schedule.cronExpression).toBe('0 12 * * *');
+            expect(result.schedule.timezone).toBe('America/New_York');
+        });
+
+        it('should default timezone to UTC when not specified in definition', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({
+                Definition: { schedule: { enabled: true, cronExpression: '0 12 * * *' } },
+            });
+            mockCommands.getScheduleByScriptName.mockResolvedValue(null);
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.schedule.timezone).toBe('UTC');
+        });
+
+        it('should return none when no schedule configured', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({ Definition: {} });
+            mockCommands.getScheduleByScriptName.mockResolvedValue(null);
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.source).toBe('none');
+            expect(result.schedule.enabled).toBe(false);
+            expect(result.schedule.scriptName).toBe('test-script');
+        });
+
+        it('should return none when definition schedule is disabled', async () => {
+            mockScriptFactory.has.mockReturnValue(true);
+            mockScriptFactory.get.mockReturnValue({
+                Definition: { schedule: { enabled: false } },
+            });
+            mockCommands.getScheduleByScriptName.mockResolvedValue(null);
+
+            const result = await useCase.execute('test-script');
+
+            expect(result.source).toBe('none');
+            expect(result.schedule.enabled).toBe(false);
+        });
+
+        it('should throw SCRIPT_NOT_FOUND error when script does not exist', async () => {
+            mockScriptFactory.has.mockReturnValue(false);
+
+            await expect(useCase.execute('non-existent'))
+                .rejects.toThrow('Script "non-existent" not found');
+
+            try {
+                await useCase.execute('non-existent');
+            } catch (error) {
+                expect(error.code).toBe('SCRIPT_NOT_FOUND');
+            }
+        });
+    });
+});

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