@friggframework/admin-scripts 2.0.0--canary.522.cbd3d5a.0 → 2.0.0--canary.517.21b69ac.0

package/PR_517_REVIEW_TRACKER.md

@@ -0,0 +1,56 @@
+# PR #517 Comment Tracker
+
+## ✅ ADDRESSED - Ready to Reply
+
+| # | File:Line | Original Comment | What We Did | Reply |
+|---|-----------|------------------|-------------|-------|
+| 1 | `admin-frigg-commands.js:15` | "I don't think this should even exist, we're just duplicating methods" | Renamed to `AdminScriptContext`, clarified as facade pattern | Renamed to `AdminScriptContext`. It's a facade - wraps repositories so scripts have one API instead of multiple imports. Open to discussing alternatives. |
+| 2 | `admin-script-base.js:94` | "Commands should come via constructor" | Changed to constructor injection | Done. Context now passed via constructor, scripts access via `this.context`. |
+| 3 | `admin-script-base.js:109` | "logging does not belong here" | Removed logging from base class | Removed. Scripts use `this.context.log()` which persists to admin process record. |
+| 4 | `admin-script-base.js:54` | "I would rename to requireIntegrationInstance" | Already renamed | Done - already renamed in current code. |
+| 5 | `admin-script-base.js:56` | "This is just a duplication of the static Definition" | Cleaned up display object | Cleaned up. `display` now only holds UI overrides (category, icon). Label/description fall back to top-level via static methods. |
+| 6 | `schedule-management-use-case.js:1` | "A use case should have single entry point" | Already split in previous session | Already split into `UpsertScheduleUseCase`, `DeleteScheduleUseCase`, `GetEffectiveScheduleUseCase`. |
+| 7 | `package.json:20` | "chai and sinon should slowly be pushed away" | Sinon removed in previous session | Sinon already removed. Will remove chai too. |
+
+---
+
+## 📝 NEEDS RESPONSE ONLY - No Code Change Required
+
+| # | File:Line | Original Comment | Reply |
+|---|-----------|------------------|-------|
+| 8 | `admin-frigg-commands.js:160` | "this does not belong here" (queueScript) | queueScript enables self-queuing pattern (fan-out, pagination, retries). It's here so scripts don't need queue internals. Could move to separate utility if preferred. |
+| 9 | `admin-script-base.js:39` | "why do we need the source?" | Distinguishes builtin vs user-defined scripts. UI can filter differently, builtins could have special handling. Could remove if not needed. |
+| 10 | `admin-script-base.js:42` | "what's the idea with these schemas?" | Optional JSON Schema for validation/documentation. Could wire to OpenAPI or dynamic UI forms. Not critical for v1 - could remove and add later. |
+| 11 | `admin-script-base.js:46` | "enabled property confusion" | Agreed the matrix is confusing. Intent: `schedule.enabled` controls auto-trigger independent of registration. Could simplify to just use presence in appDefinition. |
+| 12 | `admin-script-base.js:52` | "Do we have retry logic in place already?" | Not yet - placeholder for Phase 2. Could remove until we build it. |
+| 13 | `admin-script-base.js:81` | "What is the executionId?" | ID of AdminProcess record tracking this execution. Used to persist logs and update status. Created before script runs, passed to constructor. |
+| 14 | `schedule-management-use-case.js:89` | "why save to database if EventBridge is source of truth?" | Database stores user's config override. EventBridge is execution engine. On deploy, we sync DB to EventBridge. Tracks user config vs code default. |
+
+---
+
+## 🔧 OUTSTANDING - Needs Code Changes
+
+| # | File:Line | Original Comment | Task |
+|---|-----------|------------------|------|
+| 15 | `docs/architecture-decisions/005-admin-script-runner.md:71` | "What is 'frigg' in this parameter?" | Update ADR - rename `frigg` to `context` throughout |
+| 16 | `package.json:22` | "We already use nock for http request mocking" | Remove msw if present, use nock consistently |
+| 17 | `package.json:12` | "why mongoose?" | Check if mongoose needed or can be removed |
+| 18 | `schedule-management-use-case.js:109` | "leaking AWS specifics" | Abstract behind SchedulerAdapter, remove EventBridge references from use case |
+| 19 | `schedule-management-use-case.js:138` | "should not mention EventBridge here" | Same as above |
+| 20 | `adapters/aws-scheduler-adapter.js:30` | "should not infer/guess/default any variable" | Remove defaults, require explicit config |
+| 21 | `adapters/scheduler-adapter-factory.js:48` | "env var confusion, prefer appDefinition" | Move scheduler config to appDefinition |
+| 22 | `script-runner.js:36` | "we should not assume default values" | Remove defaults, require explicit values |
+| 23 | `dry-run-http-interceptor.js:1` | "I don't understand why this is needed" | Explain or remove - was for intercepting HTTP in dry-run mode |
+| 24 | `dry-run-repository-wrapper.js:1` | "This is smelly" | Review/remove - was for wrapping repos in dry-run mode |
+| 25 | `.github/workflows/release.yml:11` | "why do we need those?" | Check release workflow changes |
+
+---
+
+## ❓ NEEDS DISCUSSION - Architectural Decisions
+
+| # | File:Line | Original Comment | Decision Needed |
+|---|-----------|------------------|-----------------|
+| 26 | `admin-script-base.js:39` | source field | Keep BUILTIN/USER_DEFINED or remove? |
+| 27 | `admin-script-base.js:42` | inputSchema/outputSchema | Keep for future or remove for now? |
+| 28 | `admin-script-base.js:46` | schedule.enabled | Simplify to just appDefinition presence? |
+| 29 | `admin-script-base.js:52` | maxRetries | Remove placeholder or keep? |

package/index.js

@@ -8,11 +8,17 @@
 // Application Services
 const { ScriptFactory, getScriptFactory, createScriptFactory } = require('./src/application/script-factory');
 const { AdminScriptBase } = require('./src/application/admin-script-base');
-const { AdminFriggCommands, createAdminFriggCommands } = require('./src/application/admin-frigg-commands');
+const {
+    AdminScriptContext,
+    createAdminScriptContext,
+    // Legacy aliases (deprecated)
+    AdminFriggCommands,
+    createAdminFriggCommands,
+} = require('./src/application/admin-frigg-commands');
 const { ScriptRunner, createScriptRunner } = require('./src/application/script-runner');
 
 // Infrastructure
-const { adminAuthMiddleware } = require('./src/infrastructure/admin-auth-middleware');
+const { validateAdminApiKey } = require('./src/infrastructure/admin-auth-middleware');
 const { router, app, handler: routerHandler } = require('./src/infrastructure/admin-script-router');
 const { handler: executorHandler } = require('./src/infrastructure/script-executor-handler');
 
@@ -39,13 +45,16 @@ module.exports = {
     ScriptFactory,
     getScriptFactory,
     createScriptFactory,
+    AdminScriptContext,
+    createAdminScriptContext,
+    // Legacy aliases (deprecated)
     AdminFriggCommands,
     createAdminFriggCommands,
     ScriptRunner,
     createScriptRunner,
 
     // Infrastructure layer
-    adminAuthMiddleware,
+    validateAdminApiKey,
     router,
     app,
     routerHandler,

package/package.json

@@ -1,27 +1,24 @@
 {
     "name": "@friggframework/admin-scripts",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.522.cbd3d5a.0",
+    "version": "2.0.0--canary.517.21b69ac.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.522.cbd3d5a.0",
+        "@friggframework/core": "2.0.0--canary.517.21b69ac.0",
         "bcryptjs": "^2.4.3",
         "express": "^4.18.2",
         "lodash": "4.17.21",
-        "mongoose": "6.11.6",
         "serverless-http": "^3.2.0",
         "uuid": "^9.0.1"
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.522.cbd3d5a.0",
-        "@friggframework/prettier-config": "2.0.0--canary.522.cbd3d5a.0",
-        "@friggframework/test": "2.0.0--canary.522.cbd3d5a.0",
-        "chai": "^4.3.6",
+        "@friggframework/eslint-config": "2.0.0--canary.517.21b69ac.0",
+        "@friggframework/prettier-config": "2.0.0--canary.517.21b69ac.0",
+        "@friggframework/test": "2.0.0--canary.517.21b69ac.0",
         "eslint": "^8.22.0",
         "jest": "^29.7.0",
         "prettier": "^2.7.1",
-        "sinon": "^16.1.1",
         "supertest": "^7.1.4"
     },
     "scripts": {
@@ -49,5 +46,5 @@
         "maintenance",
         "operations"
     ],
-    "gitHead": "cbd3d5a81315519842f308fc0bd786a3f8786b79"
+    "gitHead": "21b69ac223278457b95dd8ba04c51d713a1c8f56"
 }

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

@@ -5,7 +5,7 @@ jest.mock('@friggframework/core/integrations/repositories/integration-repository
 jest.mock('@friggframework/core/user/repositories/user-repository-factory');
 jest.mock('@friggframework/core/modules/repositories/module-repository-factory');
 jest.mock('@friggframework/core/credential/repositories/credential-repository-factory');
-jest.mock('@friggframework/core/admin-scripts/repositories/script-execution-repository-factory');
+jest.mock('@friggframework/core/admin-scripts/repositories/admin-process-repository-factory');
 jest.mock('@friggframework/core/queues');
 
 describe('AdminFriggCommands', () => {
@@ -13,7 +13,7 @@ describe('AdminFriggCommands', () => {
     let mockUserRepo;
     let mockModuleRepo;
     let mockCredentialRepo;
-    let mockScriptExecutionRepo;
+    let mockAdminProcessRepo;
     let mockQueuerUtil;
 
     beforeEach(() => {
@@ -46,8 +46,8 @@ describe('AdminFriggCommands', () => {
             updateCredential: jest.fn(),
         };
 
-        mockScriptExecutionRepo = {
-            appendExecutionLog: jest.fn().mockResolvedValue(undefined),
+        mockAdminProcessRepo = {
+            appendProcessLog: jest.fn().mockResolvedValue(undefined),
         };
 
         mockQueuerUtil = {
@@ -60,14 +60,14 @@ describe('AdminFriggCommands', () => {
         const { createUserRepository } = require('@friggframework/core/user/repositories/user-repository-factory');
         const { createModuleRepository } = require('@friggframework/core/modules/repositories/module-repository-factory');
         const { createCredentialRepository } = require('@friggframework/core/credential/repositories/credential-repository-factory');
-        const { createScriptExecutionRepository } = require('@friggframework/core/admin-scripts/repositories/script-execution-repository-factory');
+        const { createAdminProcessRepository } = require('@friggframework/core/admin-scripts/repositories/admin-process-repository-factory');
         const { QueuerUtil } = require('@friggframework/core/queues');
 
         createIntegrationRepository.mockReturnValue(mockIntegrationRepo);
         createUserRepository.mockReturnValue(mockUserRepo);
         createModuleRepository.mockReturnValue(mockModuleRepo);
         createCredentialRepository.mockReturnValue(mockCredentialRepo);
-        createScriptExecutionRepository.mockReturnValue(mockScriptExecutionRepo);
+        createAdminProcessRepository.mockReturnValue(mockAdminProcessRepo);
 
         // Mock QueuerUtil methods
         QueuerUtil.send = mockQueuerUtil.send;
@@ -158,16 +158,16 @@ describe('AdminFriggCommands', () => {
             expect(repo).toBe(mockCredentialRepo);
         });
 
-        it('creates scriptExecutionRepository on first access', () => {
+        it('creates adminProcessRepository on first access', () => {
             const commands = new AdminFriggCommands();
-            const { createScriptExecutionRepository } = require('@friggframework/core/admin-scripts/repositories/script-execution-repository-factory');
+            const { createAdminProcessRepository } = require('@friggframework/core/admin-scripts/repositories/admin-process-repository-factory');
 
-            expect(createScriptExecutionRepository).not.toHaveBeenCalled();
+            expect(createAdminProcessRepository).not.toHaveBeenCalled();
 
-            const repo = commands.scriptExecutionRepository;
+            const repo = commands.adminProcessRepository;
 
-            expect(createScriptExecutionRepository).toHaveBeenCalledTimes(1);
-            expect(repo).toBe(mockScriptExecutionRepo);
+            expect(createAdminProcessRepository).toHaveBeenCalledTimes(1);
+            expect(repo).toBe(mockAdminProcessRepo);
         });
     });
 
@@ -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'
             );
         });
 
@@ -551,15 +551,15 @@ describe('AdminFriggCommands', () => {
         it('log() persists if executionId set', async () => {
             const commands = new AdminFriggCommands({ executionId: 'exec_123' });
             // Force repository creation
-            commands.scriptExecutionRepository;
+            commands.adminProcessRepository;
 
             commands.log('warn', 'Warning message', { detail: 'xyz' });
 
             // Give async operation a chance to execute
             await new Promise(resolve => setImmediate(resolve));
 
-            expect(mockScriptExecutionRepo.appendExecutionLog).toHaveBeenCalled();
-            const callArgs = mockScriptExecutionRepo.appendExecutionLog.mock.calls[0];
+            expect(mockAdminProcessRepo.appendProcessLog).toHaveBeenCalled();
+            const callArgs = mockAdminProcessRepo.appendProcessLog.mock.calls[0];
             expect(callArgs[0]).toBe('exec_123');
             expect(callArgs[1].level).toBe('warn');
             expect(callArgs[1].message).toBe('Warning message');
@@ -572,14 +572,14 @@ describe('AdminFriggCommands', () => {
 
             await new Promise(resolve => setImmediate(resolve));
 
-            expect(mockScriptExecutionRepo.appendExecutionLog).not.toHaveBeenCalled();
+            expect(mockAdminProcessRepo.appendProcessLog).not.toHaveBeenCalled();
         });
 
         it('log() handles persistence failure gracefully', async () => {
             const commands = new AdminFriggCommands({ executionId: 'exec_123' });
             // Force repository creation
-            commands.scriptExecutionRepository;
-            mockScriptExecutionRepo.appendExecutionLog.mockRejectedValue(new Error('DB Error'));
+            commands.adminProcessRepository;
+            mockAdminProcessRepo.appendProcessLog.mockRejectedValue(new Error('DB Error'));
 
             // Should not throw
             expect(() => commands.log('error', 'Test error')).not.toThrow();

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

@@ -28,12 +28,11 @@ describe('AdminScriptBase', () => {
                     config: {
                         timeout: 600000,
                         maxRetries: 3,
-                        requiresIntegrationFactory: true,
+                        requireIntegrationInstance: true,
                     },
                     display: {
-                        label: 'Test Script',
-                        description: 'For testing',
                         category: 'testing',
+                        icon: 'test-icon',
                     },
                 };
             }
@@ -45,6 +44,15 @@ describe('AdminScriptBase', () => {
             expect(TestScript.Definition.schedule.enabled).toBe(true);
             expect(TestScript.Definition.config.timeout).toBe(600000);
         });
+
+        it('should have clean display object without redundant fields', () => {
+            // Default display should only have UI-specific fields
+            expect(AdminScriptBase.Definition.display).toBeDefined();
+            expect(AdminScriptBase.Definition.display.category).toBe('maintenance');
+            // Should NOT have redundant label/description
+            expect(AdminScriptBase.Definition.display.label).toBeUndefined();
+            expect(AdminScriptBase.Definition.display.description).toBeUndefined();
+        });
     });
 
     describe('Static methods', () => {
@@ -90,18 +98,68 @@ describe('AdminScriptBase', () => {
                 source: 'USER_DEFINED',
             });
         });
+
+        it('getDisplayLabel() should return display.label or fall back to name', () => {
+            class ScriptWithLabel extends AdminScriptBase {
+                static Definition = {
+                    name: 'my-script',
+                    version: '1.0.0',
+                    description: 'test',
+                    display: { label: 'My Custom Label' },
+                };
+            }
+
+            class ScriptWithoutLabel extends AdminScriptBase {
+                static Definition = {
+                    name: 'another-script',
+                    version: '1.0.0',
+                    description: 'test',
+                };
+            }
+
+            expect(ScriptWithLabel.getDisplayLabel()).toBe('My Custom Label');
+            expect(ScriptWithoutLabel.getDisplayLabel()).toBe('another-script');
+        });
+
+        it('getDisplayDescription() should return display.description or fall back to description', () => {
+            class ScriptWithDisplayDesc extends AdminScriptBase {
+                static Definition = {
+                    name: 'my-script',
+                    version: '1.0.0',
+                    description: 'Technical description',
+                    display: { description: 'User-friendly description' },
+                };
+            }
+
+            class ScriptWithoutDisplayDesc extends AdminScriptBase {
+                static Definition = {
+                    name: 'another-script',
+                    version: '1.0.0',
+                    description: 'Technical description',
+                };
+            }
+
+            expect(ScriptWithDisplayDesc.getDisplayDescription()).toBe('User-friendly description');
+            expect(ScriptWithoutDisplayDesc.getDisplayDescription()).toBe('Technical description');
+        });
     });
 
     describe('Constructor', () => {
         it('should initialize with default values', () => {
             const script = new AdminScriptBase();
 
+            expect(script.context).toBeNull();
             expect(script.executionId).toBeNull();
-            expect(script.logs).toEqual([]);
-            expect(script._startTime).toBeNull();
             expect(script.integrationFactory).toBeNull();
         });
 
+        it('should accept context parameter', () => {
+            const mockContext = { log: jest.fn() };
+            const script = new AdminScriptBase({ context: mockContext });
+
+            expect(script.context).toBe(mockContext);
+        });
+
         it('should accept executionId parameter', () => {
             const script = new AdminScriptBase({ executionId: 'exec_123' });
 
@@ -117,13 +175,16 @@ describe('AdminScriptBase', () => {
             expect(script.integrationFactory).toBe(mockFactory);
         });
 
-        it('should accept both executionId and integrationFactory', () => {
+        it('should accept all parameters together', () => {
+            const mockContext = { log: jest.fn() };
             const mockFactory = { mock: true };
             const script = new AdminScriptBase({
+                context: mockContext,
                 executionId: 'exec_456',
                 integrationFactory: mockFactory,
             });
 
+            expect(script.context).toBe(mockContext);
             expect(script.executionId).toBe('exec_456');
             expect(script.integrationFactory).toBe(mockFactory);
         });
@@ -133,12 +194,12 @@ describe('AdminScriptBase', () => {
         it('should throw error when not implemented by subclass', async () => {
             const script = new AdminScriptBase();
 
-            await expect(script.execute({}, {})).rejects.toThrow(
+            await expect(script.execute({})).rejects.toThrow(
                 'AdminScriptBase.execute() must be implemented by subclass'
             );
         });
 
-        it('should allow child classes to implement execute()', async () => {
+        it('should allow child classes to implement execute() with params only', async () => {
             class TestScript extends AdminScriptBase {
                 static Definition = {
                     name: 'test',
@@ -146,128 +207,83 @@ describe('AdminScriptBase', () => {
                     description: 'test',
                 };
 
-                async execute(frigg, params) {
+                async execute(params) {
                     return { result: 'success', params };
                 }
             }
 
             const script = new TestScript();
-            const frigg = {};
             const params = { foo: 'bar' };
 
-            const result = await script.execute(frigg, params);
+            const result = await script.execute(params);
 
             expect(result.result).toBe('success');
             expect(result.params).toEqual({ foo: 'bar' });
         });
-    });
-
-    describe('Logging methods', () => {
-        it('log() should create log entry with timestamp', () => {
-            const script = new AdminScriptBase();
-            const beforeTime = new Date().toISOString();
-
-            const entry = script.log('info', 'Test message', { key: 'value' });
-
-            const afterTime = new Date().toISOString();
-
-            expect(entry.level).toBe('info');
-            expect(entry.message).toBe('Test message');
-            expect(entry.data).toEqual({ key: 'value' });
-            expect(entry.timestamp).toBeDefined();
-            expect(entry.timestamp >= beforeTime).toBe(true);
-            expect(entry.timestamp <= afterTime).toBe(true);
-        });
-
-        it('log() should add entry to logs array', () => {
-            const script = new AdminScriptBase();
-
-            script.log('info', 'First');
-            script.log('error', 'Second');
-            script.log('warn', 'Third');
-
-            const logs = script.getLogs();
-
-            expect(logs).toHaveLength(3);
-            expect(logs[0].message).toBe('First');
-            expect(logs[1].message).toBe('Second');
-            expect(logs[2].message).toBe('Third');
-        });
-
-        it('log() should default data to empty object', () => {
-            const script = new AdminScriptBase();
-
-            const entry = script.log('info', 'No data');
 
-            expect(entry.data).toEqual({});
-        });
-
-        it('getLogs() should return logs array', () => {
-            const script = new AdminScriptBase();
-
-            script.log('info', 'Message 1');
-            script.log('error', 'Message 2');
-
-            const logs = script.getLogs();
-
-            expect(logs).toHaveLength(2);
-            expect(logs[0].level).toBe('info');
-            expect(logs[1].level).toBe('error');
-        });
+        it('should access context via this.context', async () => {
+            class TestScript extends AdminScriptBase {
+                static Definition = {
+                    name: 'test',
+                    version: '1.0.0',
+                    description: 'test',
+                };
 
-        it('clearLogs() should empty logs array', () => {
-            const script = new AdminScriptBase();
+                async execute(params) {
+                    this.context.log('info', 'Starting');
+                    return { success: true };
+                }
+            }
 
-            script.log('info', 'Message 1');
-            script.log('info', 'Message 2');
-            expect(script.getLogs()).toHaveLength(2);
+            const mockContext = { log: jest.fn() };
+            const script = new TestScript({ context: mockContext });
 
-            script.clearLogs();
+            await script.execute({});
 
-            expect(script.getLogs()).toHaveLength(0);
+            expect(mockContext.log).toHaveBeenCalledWith('info', 'Starting');
         });
     });
 
     describe('Integration with child classes', () => {
-        it('should support full lifecycle', async () => {
+        it('should support full lifecycle with context injection', async () => {
             class MyScript extends AdminScriptBase {
                 static Definition = {
                     name: 'my-script',
                     version: '1.0.0',
                     description: 'My test script',
                     config: {
-                        requiresIntegrationFactory: true,
+                        requireIntegrationInstance: true,
                     },
                 };
 
-                async execute(frigg, params) {
-                    this.log('info', 'Starting execution');
-                    this.log('debug', 'Processing', params);
+                async execute(params) {
+                    this.context.log('info', 'Starting execution');
+                    this.context.log('debug', 'Processing', params);
 
                     if (this.integrationFactory) {
-                        this.log('info', 'Integration factory available');
+                        this.context.log('info', 'Integration factory available');
                     }
 
                     return { processed: true };
                 }
             }
 
+            const mockContext = { log: jest.fn() };
             const mockFactory = { getInstanceById: jest.fn() };
             const script = new MyScript({
+                context: mockContext,
                 executionId: 'exec_789',
                 integrationFactory: mockFactory,
             });
 
-            const frigg = {};
-            const result = await script.execute(frigg, { test: 'data' });
+            const result = await script.execute({ test: 'data' });
 
             expect(result).toEqual({ processed: true });
 
-            const logs = script.getLogs();
-            expect(logs).toHaveLength(3);
-            expect(logs[0].message).toBe('Starting execution');
-            expect(logs[1].message).toBe('Processing');
-            expect(logs[2].message).toBe('Integration factory available');
+            expect(mockContext.log).toHaveBeenCalledTimes(3);
+            expect(mockContext.log).toHaveBeenCalledWith('info', 'Starting execution');
+            expect(mockContext.log).toHaveBeenCalledWith('debug', 'Processing', { test: 'data' });
+            expect(mockContext.log).toHaveBeenCalledWith('info', 'Integration factory available');
         });
     });
 });