@friggframework/admin-scripts 2.0.0--canary.517.8d90337.0 → 2.0.0--canary.517.095e3f6.0

package/index.js

@@ -6,15 +6,12 @@
  */
 
 // Application Services
-const {
-    ScriptFactory,
-    getScriptFactory,
-} = require('./src/application/script-factory');
+const { ScriptFactory } = require('./src/application/script-factory');
 const { AdminScriptBase } = require('./src/application/admin-script-base');
 const {
     AdminScriptContext,
     createAdminScriptContext,
-} = require('./src/application/admin-frigg-commands');
+} = require('./src/application/admin-script-context');
 const {
     ScriptRunner,
     createScriptRunner,
@@ -47,7 +44,6 @@ module.exports = {
     // Application layer
     AdminScriptBase,
     ScriptFactory,
-    getScriptFactory,
     AdminScriptContext,
     createAdminScriptContext,
     ScriptRunner,

package/package.json

@@ -1,19 +1,19 @@
 {
     "name": "@friggframework/admin-scripts",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.517.8d90337.0",
+    "version": "2.0.0--canary.517.095e3f6.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.8d90337.0",
+        "@friggframework/core": "2.0.0--canary.517.095e3f6.0",
         "@hapi/boom": "^10.0.1",
         "express": "^4.18.2",
         "serverless-http": "^3.2.0"
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.517.8d90337.0",
-        "@friggframework/prettier-config": "2.0.0--canary.517.8d90337.0",
-        "@friggframework/test": "2.0.0--canary.517.8d90337.0",
+        "@friggframework/eslint-config": "2.0.0--canary.517.095e3f6.0",
+        "@friggframework/prettier-config": "2.0.0--canary.517.095e3f6.0",
+        "@friggframework/test": "2.0.0--canary.517.095e3f6.0",
         "eslint": "^8.22.0",
         "jest": "^29.7.0",
         "prettier": "^2.7.1",
@@ -44,5 +44,5 @@
         "maintenance",
         "operations"
     ],
-    "gitHead": "8d903378eed651256cbda1a3e1a6aab54fa46475"
+    "gitHead": "095e3f64ffc59fd7afc713a537c69a0ec48eef7b"
 }

package/src/application/__tests__/{admin-frigg-commands.test.js → admin-script-context.test.js}

@@ -1,7 +1,7 @@
 const {
     AdminScriptContext,
     createAdminScriptContext,
-} = require('../admin-frigg-commands');
+} = require('../admin-script-context');
 
 // Mock all repository factories
 jest.mock(

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

@@ -1,4 +1,4 @@
-const { ScriptFactory, getScriptFactory } = require('../script-factory');
+const { ScriptFactory } = require('../script-factory');
 const { AdminScriptBase } = require('../admin-script-base');
 
 describe('ScriptFactory', () => {
@@ -333,15 +333,32 @@ describe('ScriptFactory', () => {
         });
     });
 
-    describe('Global factory functions', () => {
-        it('getScriptFactory() should return singleton instance', () => {
-            const factory1 = getScriptFactory();
-            const factory2 = getScriptFactory();
+    describe('constructor', () => {
+        it('registers scripts passed to the constructor', () => {
+            class ScriptOne extends AdminScriptBase {
+                static Definition = {
+                    name: 'script-one',
+                    version: '1.0.0',
+                    description: 'One',
+                };
+            }
+            class ScriptTwo extends AdminScriptBase {
+                static Definition = {
+                    name: 'script-two',
+                    version: '1.0.0',
+                    description: 'Two',
+                };
+            }
 
-            expect(factory1).toBe(factory2);
-            expect(factory1).toBeInstanceOf(ScriptFactory);
+            const factory = new ScriptFactory([ScriptOne, ScriptTwo]);
+
+            expect(factory.size).toBe(2);
+            expect(factory.has('script-one')).toBe(true);
+            expect(factory.has('script-two')).toBe(true);
         });
+    });
 
+    describe('Instance independence', () => {
         it('new ScriptFactory() creates independent instances', () => {
             const factory1 = new ScriptFactory();
             const factory2 = new ScriptFactory();
@@ -351,7 +368,7 @@ describe('ScriptFactory', () => {
             expect(factory2).toBeInstanceOf(ScriptFactory);
         });
 
-        it('global factory should be independent from created instances', () => {
+        it('registering into one factory does not affect another', () => {
             class TestScript extends AdminScriptBase {
                 static Definition = {
                     name: 'test',
@@ -360,18 +377,12 @@ describe('ScriptFactory', () => {
                 };
             }
 
-            const customFactory = new ScriptFactory();
-            customFactory.register(TestScript);
-
-            const globalFactory = getScriptFactory();
-
-            // Custom factory has the script
-            expect(customFactory.has('test')).toBe(true);
+            const factoryA = new ScriptFactory();
+            const factoryB = new ScriptFactory();
+            factoryA.register(TestScript);
 
-            // Global factory doesn't (assuming it's empty or has different scripts)
-            // We can't make assumptions about global factory state in tests
-            // so we just verify they're different instances
-            expect(customFactory).not.toBe(globalFactory);
+            expect(factoryA.has('test')).toBe(true);
+            expect(factoryB.has('test')).toBe(false);
         });
     });
 

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

@@ -3,10 +3,10 @@ const { ScriptFactory } = require('../script-factory');
 const { AdminScriptBase } = require('../admin-script-base');
 
 // Mock dependencies
-jest.mock('../admin-frigg-commands');
+jest.mock('../admin-script-context');
 jest.mock('@friggframework/core/application/commands/admin-script-commands');
 
-const { createAdminScriptContext } = require('../admin-frigg-commands');
+const { createAdminScriptContext } = require('../admin-script-context');
 const {
     createAdminScriptCommands,
 } = require('@friggframework/core/application/commands/admin-script-commands');
@@ -292,12 +292,13 @@ describe('ScriptRunner', () => {
     });
 
     describe('createScriptRunner()', () => {
-        it('should create runner with default factory', () => {
-            const runner = createScriptRunner();
-            expect(runner).toBeInstanceOf(ScriptRunner);
+        it('should throw when no scriptFactory is provided', () => {
+            expect(() => createScriptRunner()).toThrow(
+                'ScriptRunner requires a scriptFactory'
+            );
         });
 
-        it('should create runner with custom params', () => {
+        it('should create runner with an injected factory', () => {
             const customFactory = new ScriptFactory();
             const runner = createScriptRunner({ scriptFactory: customFactory });
             expect(runner).toBeInstanceOf(ScriptRunner);

package/src/application/script-factory.js

@@ -4,11 +4,18 @@
  * Registry and factory for admin scripts.
  * Manages script registration, validation, and instantiation.
  *
+ * Instances are created and owned by the caller (see bootstrap.js, which builds
+ * one per process and injects it into the runner and router). There is no global
+ * instance — pass a factory explicitly wherever one is needed.
+ *
  * Usage:
  * ```javascript
- * const factory = new ScriptFactory();
- * factory.register(MyScript);
- * const script = factory.createInstance('my-script', { executionId: '123' });
+ * const factory = new ScriptFactory([MyScript]);
+ * const script = factory.createInstance('my-script', {
+ *     context,
+ *     executionId,
+ *     integrationFactory,
+ * });
  * ```
  */
 class ScriptFactory {
@@ -137,18 +144,4 @@ class ScriptFactory {
     }
 }
 
-// Singleton instance for global use
-let globalFactory = null;
-
-/**
- * Get global script factory instance
- * @returns {ScriptFactory} Global factory
- */
-function getScriptFactory() {
-    if (!globalFactory) {
-        globalFactory = new ScriptFactory();
-    }
-    return globalFactory;
-}
-
-module.exports = { ScriptFactory, getScriptFactory };
+module.exports = { ScriptFactory };

package/src/application/script-runner.js

@@ -1,5 +1,4 @@
-const { getScriptFactory } = require('./script-factory');
-const { createAdminScriptContext } = require('./admin-frigg-commands');
+const { createAdminScriptContext } = require('./admin-script-context');
 const {
     createAdminScriptCommands,
 } = require('@friggframework/core/application/commands/admin-script-commands');
@@ -14,8 +13,20 @@ const {
  * - Status updates
  */
 class ScriptRunner {
+    /**
+     * @param {Object} params
+     * @param {ScriptFactory} params.scriptFactory - Required. The registry used
+     *   to resolve and instantiate scripts by name (built by bootstrap.js).
+     * @param {Object} [params.commands] - Admin process command layer; defaults
+     *   to a fresh createAdminScriptCommands().
+     * @param {Object} [params.integrationFactory] - Hydrates integration
+     *   instances for scripts that need them.
+     */
     constructor(params = {}) {
-        this.scriptFactory = params.scriptFactory || getScriptFactory();
+        if (!params.scriptFactory) {
+            throw new Error('ScriptRunner requires a scriptFactory');
+        }
+        this.scriptFactory = params.scriptFactory;
         this.commands = params.commands || createAdminScriptCommands();
         this.integrationFactory = params.integrationFactory || null;
     }

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

@@ -10,16 +10,13 @@ jest.mock('../admin-auth-middleware', () => ({
     },
 }));
 
-jest.mock('../../application/script-factory');
 jest.mock('../../application/script-runner');
 jest.mock('@friggframework/core/application/commands/admin-script-commands');
 jest.mock('@friggframework/core/queues');
 jest.mock('../../adapters/scheduler-adapter-factory');
-jest.mock('../bootstrap', () => ({
-    bootstrapAdminScripts: () => ({ integrationFactory: {} }),
-}));
+jest.mock('../bootstrap');
 
-const { getScriptFactory } = require('../../application/script-factory');
+const { bootstrapAdminScripts } = require('../bootstrap');
 const { createScriptRunner } = require('../../application/script-runner');
 const {
     createAdminScriptCommands,
@@ -72,7 +69,10 @@ describe('Admin Script Router', () => {
             setScheduleEnabled: jest.fn(),
         };
 
-        getScriptFactory.mockReturnValue(mockFactory);
+        bootstrapAdminScripts.mockReturnValue({
+            scriptFactory: mockFactory,
+            integrationFactory: {},
+        });
         createScriptRunner.mockReturnValue(mockRunner);
         createAdminScriptCommands.mockReturnValue(mockCommands);
         createSchedulerAdapter.mockReturnValue(mockSchedulerAdapter);
@@ -174,6 +174,10 @@ describe('Admin Script Router', () => {
                     mode: 'sync',
                 })
             );
+            expect(createScriptRunner).toHaveBeenCalledWith({
+                scriptFactory: mockFactory,
+                integrationFactory: {},
+            });
         });
 
         it('should queue script for async execution', async () => {

package/src/infrastructure/__tests__/bootstrap.test.js

@@ -0,0 +1,78 @@
+const { ScriptFactory } = require('../../application/script-factory');
+const { AdminScriptBase } = require('../../application/admin-script-base');
+
+jest.mock('@friggframework/core/handlers/app-definition-loader');
+
+const {
+    loadAppDefinition,
+} = require('@friggframework/core/handlers/app-definition-loader');
+const {
+    bootstrapAdminScripts,
+    _resetBootstrapForTests,
+} = require('../bootstrap');
+
+class TestScript extends AdminScriptBase {
+    static Definition = {
+        name: 'test-script',
+        version: '1.0.0',
+        description: 'Test script',
+    };
+}
+
+describe('bootstrapAdminScripts', () => {
+    beforeEach(() => {
+        _resetBootstrapForTests();
+        jest.clearAllMocks();
+        jest.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        console.error.mockRestore();
+    });
+
+    it('registers the app definition admin scripts into the returned factory', () => {
+        loadAppDefinition.mockReturnValue({ adminScripts: [TestScript] });
+
+        const { scriptFactory, integrationFactory } = bootstrapAdminScripts();
+
+        expect(scriptFactory).toBeInstanceOf(ScriptFactory);
+        expect(scriptFactory.has('test-script')).toBe(true);
+        expect(integrationFactory).toBeTruthy();
+    });
+
+    it('never throws and returns an empty factory when the app definition cannot load', () => {
+        loadAppDefinition.mockImplementation(() => {
+            throw new Error('cannot load app definition');
+        });
+
+        let result;
+        expect(() => {
+            result = bootstrapAdminScripts();
+        }).not.toThrow();
+
+        expect(result.scriptFactory).toBeInstanceOf(ScriptFactory);
+        expect(result.scriptFactory.size).toBe(0);
+        expect(result.integrationFactory).toBeTruthy();
+        expect(console.error).toHaveBeenCalled();
+    });
+
+    it('memoizes: repeated calls reuse the same factory and load the definition once', () => {
+        loadAppDefinition.mockReturnValue({ adminScripts: [TestScript] });
+
+        const first = bootstrapAdminScripts();
+        const second = bootstrapAdminScripts();
+
+        expect(second.scriptFactory).toBe(first.scriptFactory);
+        expect(second.integrationFactory).toBe(first.integrationFactory);
+        expect(loadAppDefinition).toHaveBeenCalledTimes(1);
+    });
+
+    it('tolerates an app definition with no adminScripts', () => {
+        loadAppDefinition.mockReturnValue({});
+
+        const { scriptFactory } = bootstrapAdminScripts();
+
+        expect(scriptFactory).toBeInstanceOf(ScriptFactory);
+        expect(scriptFactory.size).toBe(0);
+    });
+});

package/src/infrastructure/__tests__/script-executor-handler.test.js

@@ -0,0 +1,163 @@
+jest.mock('../bootstrap');
+jest.mock('../../application/script-runner');
+jest.mock('@friggframework/core/application/commands/admin-script-commands');
+
+const { bootstrapAdminScripts } = require('../bootstrap');
+const { createScriptRunner } = require('../../application/script-runner');
+const {
+    createAdminScriptCommands,
+} = require('@friggframework/core/application/commands/admin-script-commands');
+const { handler } = require('../script-executor-handler');
+
+describe('Admin Script Executor Handler', () => {
+    let mockScriptFactory;
+    let mockIntegrationFactory;
+    let mockRunner;
+    let mockCommands;
+
+    beforeEach(() => {
+        mockScriptFactory = { id: 'script-factory' };
+        mockIntegrationFactory = { id: 'integration-factory' };
+        mockRunner = { execute: jest.fn() };
+        mockCommands = {
+            completeAdminProcess: jest.fn().mockResolvedValue({}),
+        };
+
+        bootstrapAdminScripts.mockReturnValue({
+            scriptFactory: mockScriptFactory,
+            integrationFactory: mockIntegrationFactory,
+        });
+        createScriptRunner.mockReturnValue(mockRunner);
+        createAdminScriptCommands.mockReturnValue(mockCommands);
+
+        jest.spyOn(console, 'log').mockImplementation(() => {});
+        jest.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        console.log.mockRestore();
+        console.error.mockRestore();
+        jest.clearAllMocks();
+    });
+
+    describe('EventBridge Scheduler direct invoke (no Records)', () => {
+        it('injects the bootstrapped factory into the runner and reports the result', async () => {
+            mockRunner.execute.mockResolvedValue({
+                status: 'COMPLETED',
+                executionId: 'exec-1',
+            });
+
+            const response = await handler({
+                scriptName: 'my-script',
+                trigger: 'SCHEDULED',
+                params: { foo: 'bar' },
+            });
+
+            expect(createScriptRunner).toHaveBeenCalledWith({
+                scriptFactory: mockScriptFactory,
+                integrationFactory: mockIntegrationFactory,
+            });
+            expect(mockRunner.execute).toHaveBeenCalledWith(
+                'my-script',
+                { foo: 'bar' },
+                expect.objectContaining({ trigger: 'SCHEDULED', mode: 'async' })
+            );
+
+            expect(response.statusCode).toBe(200);
+            const body = JSON.parse(response.body);
+            expect(body.processed).toBe(1);
+            expect(body.results[0]).toEqual({
+                scriptName: 'my-script',
+                status: 'COMPLETED',
+                executionId: 'exec-1',
+            });
+        });
+
+        it('marks the execution FAILED when the runner throws', async () => {
+            mockRunner.execute.mockRejectedValue(new Error('boom'));
+
+            const response = await handler({
+                scriptName: 'my-script',
+                executionId: 'exec-2',
+                trigger: 'SCHEDULED',
+            });
+
+            expect(response.statusCode).toBe(200);
+            const body = JSON.parse(response.body);
+            expect(body.results[0].status).toBe('FAILED');
+            expect(mockCommands.completeAdminProcess).toHaveBeenCalledWith(
+                'exec-2',
+                expect.objectContaining({ state: 'FAILED' })
+            );
+        });
+    });
+
+    describe('SQS batch (Records[])', () => {
+        it('injects the bootstrapped factory and processes each record', async () => {
+            mockRunner.execute.mockResolvedValue({
+                status: 'COMPLETED',
+                executionId: 'exec-3',
+            });
+
+            const response = await handler({
+                Records: [
+                    {
+                        body: JSON.stringify({
+                            scriptName: 'my-script',
+                            executionId: 'exec-3',
+                            params: {},
+                        }),
+                    },
+                ],
+            });
+
+            expect(createScriptRunner).toHaveBeenCalledWith({
+                scriptFactory: mockScriptFactory,
+                integrationFactory: mockIntegrationFactory,
+            });
+            expect(mockRunner.execute).toHaveBeenCalledWith(
+                'my-script',
+                {},
+                expect.objectContaining({
+                    trigger: 'QUEUE',
+                    executionId: 'exec-3',
+                })
+            );
+
+            expect(response.statusCode).toBe(200);
+            const body = JSON.parse(response.body);
+            expect(body.processed).toBe(1);
+            expect(body.results[0].status).toBe('COMPLETED');
+        });
+
+        it('isolates a bad record without dropping the rest of the batch', async () => {
+            mockRunner.execute.mockResolvedValue({
+                status: 'COMPLETED',
+                executionId: 'exec-4',
+            });
+
+            const response = await handler({
+                Records: [
+                    // Missing scriptName -> runMessage throws before the runner
+                    { body: JSON.stringify({ executionId: 'exec-bad' }) },
+                    {
+                        body: JSON.stringify({
+                            scriptName: 'my-script',
+                            executionId: 'exec-4',
+                            params: {},
+                        }),
+                    },
+                ],
+            });
+
+            const body = JSON.parse(response.body);
+            expect(body.processed).toBe(2);
+            expect(body.results[0].status).toBe('FAILED');
+            expect(body.results[1].status).toBe('COMPLETED');
+            expect(mockCommands.completeAdminProcess).toHaveBeenCalledWith(
+                'exec-bad',
+                expect.objectContaining({ state: 'FAILED' })
+            );
+        });
+    });
+});

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

@@ -2,7 +2,6 @@ const express = require('express');
 const serverless = require('serverless-http');
 const Boom = require('@hapi/boom');
 const { validateAdminApiKey } = require('./admin-auth-middleware');
-const { getScriptFactory } = require('../application/script-factory');
 const { createScriptRunner } = require('../application/script-runner');
 const {
     validateScriptInput,
@@ -27,10 +26,13 @@ const router = express.Router();
 // Apply auth middleware to all admin routes
 router.use(validateAdminApiKey);
 
-// Register the host app's admin scripts before handling requests.
-// Memoized, so this only does work on the first request per process.
-router.use((_req, _res, next) => {
-    bootstrapAdminScripts();
+// Build (once, memoized) and inject the per-process dependencies onto the
+// request, so route handlers consume them explicitly instead of reaching for a
+// global. Registers the host app's admin scripts on the first request.
+router.use((req, _res, next) => {
+    const { scriptFactory, integrationFactory } = bootstrapAdminScripts();
+    req.scriptFactory = scriptFactory;
+    req.integrationFactory = integrationFactory;
     next();
 });
 
@@ -42,7 +44,9 @@ router.use((_req, _res, next) => {
  */
 function sendError(res, error, fallbackMessage) {
     if (error.isBoom) {
-        return res.status(error.output.statusCode).json({ error: error.message });
+        return res
+            .status(error.output.statusCode)
+            .json({ error: error.message });
     }
     console.error(fallbackMessage, error);
     return res.status(500).json({ error: fallbackMessage });
@@ -65,9 +69,10 @@ function buildAudit(req) {
 
 /**
  * Create schedule use case instances
+ * @param {ScriptFactory} scriptFactory - Registry injected from the request.
  * @private
  */
-function createScheduleUseCases() {
+function createScheduleUseCases(scriptFactory) {
     const commands = createAdminScriptCommands();
 
     // The local adapter is in-memory only (schedules vanish on cold start), so it
@@ -88,7 +93,6 @@ function createScheduleUseCases() {
         scheduleGroupName: process.env.ADMIN_SCRIPT_SCHEDULE_GROUP,
         roleArn: process.env.SCHEDULER_ROLE_ARN,
     });
-    const scriptFactory = getScriptFactory();
 
     return {
         getEffectiveSchedule: new GetEffectiveScheduleUseCase({
@@ -114,7 +118,7 @@ function createScheduleUseCases() {
  */
 router.get('/scripts', async (req, res) => {
     try {
-        const factory = getScriptFactory();
+        const factory = req.scriptFactory;
         const scripts = factory.getAll();
 
         res.json({
@@ -140,7 +144,7 @@ router.get('/scripts', async (req, res) => {
 router.get('/scripts/:scriptName', async (req, res) => {
     try {
         const { scriptName } = req.params;
-        const factory = getScriptFactory();
+        const factory = req.scriptFactory;
 
         if (!factory.has(scriptName)) {
             return res.status(404).json({
@@ -175,7 +179,7 @@ router.post('/scripts/:scriptName/validate', async (req, res) => {
     try {
         const { scriptName } = req.params;
         const { params = {} } = req.body;
-        const factory = getScriptFactory();
+        const factory = req.scriptFactory;
 
         if (!factory.has(scriptName)) {
             return res.status(404).json({
@@ -200,7 +204,7 @@ router.post('/scripts/:scriptName', async (req, res) => {
     try {
         const { scriptName } = req.params;
         const { params = {}, mode = 'async' } = req.body;
-        const factory = getScriptFactory();
+        const factory = req.scriptFactory;
 
         if (!factory.has(scriptName)) {
             return res.status(404).json({
@@ -237,8 +241,10 @@ router.post('/scripts/:scriptName', async (req, res) => {
                 });
             }
 
-            const { integrationFactory } = bootstrapAdminScripts();
-            const runner = createScriptRunner({ integrationFactory });
+            const runner = createScriptRunner({
+                scriptFactory: req.scriptFactory,
+                integrationFactory: req.integrationFactory,
+            });
             const result = await runner.execute(scriptName, params, {
                 trigger: 'MANUAL',
                 mode: 'sync',
@@ -355,7 +361,9 @@ router.get('/scripts/:scriptName/executions', async (req, res) => {
 router.get('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
-        const { getEffectiveSchedule } = createScheduleUseCases();
+        const { getEffectiveSchedule } = createScheduleUseCases(
+            req.scriptFactory
+        );
 
         const result = await getEffectiveSchedule.execute(scriptName);
 
@@ -377,7 +385,7 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
         const { enabled, cronExpression, timezone } = req.body;
-        const { upsertSchedule } = createScheduleUseCases();
+        const { upsertSchedule } = createScheduleUseCases(req.scriptFactory);
 
         const result = await upsertSchedule.execute(scriptName, {
             enabled,
@@ -407,7 +415,7 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
 router.delete('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
-        const { deleteSchedule } = createScheduleUseCases();
+        const { deleteSchedule } = createScheduleUseCases(req.scriptFactory);
 
         const result = await deleteSchedule.execute(scriptName);
 

package/src/infrastructure/bootstrap.js

@@ -1,18 +1,20 @@
-const { getScriptFactory } = require('../application/script-factory');
+const { ScriptFactory } = require('../application/script-factory');
 
 /**
  * Admin Script Bootstrap
  *
- * Loads the host app's definition at Lambda runtime and registers its admin
- * scripts (and the built-ins, when enabled) into the global ScriptFactory, so
- * the router and SQS worker can resolve scripts by name. Also constructs the
- * integrationFactory used by scripts that need hydrated integration instances.
+ * Composition root for the admin-scripts runtime. Loads the host app's
+ * definition at Lambda runtime, builds a ScriptFactory, and registers the app's
+ * admin scripts into it so the router and SQS worker can resolve scripts by
+ * name. Also constructs the integrationFactory used by scripts that need
+ * hydrated integration instances. Both are returned for the caller to inject.
  *
  * Runs once per process (memoized) and never throws — a missing/unloadable app
  * definition is logged and leaves the factory empty rather than crashing the
  * Lambda cold start.
  */
 let bootstrapped = false;
+let scriptFactory = null;
 let integrationFactory = null;
 
 function registerScripts(factory, scriptClasses) {
@@ -43,22 +45,26 @@ function createIntegrationFactory() {
 }
 
 /**
- * @returns {{ integrationFactory: object }}
+ * @returns {{ scriptFactory: ScriptFactory, integrationFactory: object }}
  */
 function bootstrapAdminScripts() {
     if (bootstrapped) {
-        return { integrationFactory };
+        return { scriptFactory, integrationFactory };
     }
     bootstrapped = true;
 
+    // Create the registry up front so consumers always get a (possibly empty)
+    // factory even when the app definition can't be loaded — mirrors the
+    // never-throw contract above.
+    scriptFactory = new ScriptFactory();
+
     try {
         const {
             loadAppDefinition,
         } = require('@friggframework/core/handlers/app-definition-loader');
         const { adminScripts = [] } = loadAppDefinition();
 
-        const factory = getScriptFactory();
-        registerScripts(factory, adminScripts);
+        registerScripts(scriptFactory, adminScripts);
     } catch (error) {
         console.error(
             '[admin-scripts] bootstrap: could not load app definition:',
@@ -67,12 +73,13 @@ function bootstrapAdminScripts() {
     }
 
     integrationFactory = createIntegrationFactory();
-    return { integrationFactory };
+    return { scriptFactory, integrationFactory };
 }
 
 /** Test-only: reset memoized bootstrap state. */
 function _resetBootstrapForTests() {
     bootstrapped = false;
+    scriptFactory = null;
     integrationFactory = null;
 }
 

package/src/infrastructure/script-executor-handler.js

@@ -6,9 +6,20 @@ const { bootstrapAdminScripts } = require('./bootstrap');
 
 /**
  * Run a single execution message through the ScriptRunner.
+ * @param {Object} message - Parsed execution message.
+ * @param {string} message.scriptName - Name of the registered script to run (required).
+ * @param {string} [message.executionId] - Existing AdminProcess id to resume; when
+ *   absent, ScriptRunner creates a new record.
+ * @param {string} [message.trigger] - Execution trigger; defaults to 'QUEUE'.
+ * @param {Object} [message.params] - Parameters passed to the script.
+ * @param {string} [message.parentExecutionId] - Parent execution id for queueScript continuations.
+ * @param {Object} deps
+ * @param {ScriptFactory} deps.scriptFactory - Registry used to resolve and instantiate the script.
+ * @param {Object} deps.integrationFactory - Hydrates integration instances for scripts that need them.
+ * @returns {Promise<{ scriptName: string, status: string, executionId: string }>}
  * @private
  */
-async function runMessage(message, integrationFactory) {
+async function runMessage(message, { scriptFactory, integrationFactory }) {
     const { scriptName, executionId, trigger, params, parentExecutionId } =
         message;
 
@@ -22,7 +33,7 @@ async function runMessage(message, integrationFactory) {
         }`
     );
 
-    const runner = createScriptRunner({ integrationFactory });
+    const runner = createScriptRunner({ scriptFactory, integrationFactory });
     const result = await runner.execute(scriptName, params, {
         trigger: trigger || 'QUEUE',
         mode: 'async',
@@ -66,59 +77,58 @@ async function markFailed(executionId, error) {
 }
 
 /**
- * Admin Script Executor Lambda Handler
- *
- * Handles two invocation shapes:
- * - SQS: `event.Records[]` — each record body is a JSON execution message
- *   (manual async executions and queueScript continuations).
- * - EventBridge Scheduler direct invoke: the event itself is the message
- *   (`{ scriptName, trigger: 'SCHEDULED', params }`) with no `Records` wrapper.
- *
- * Thin adapter: parses the event and delegates to ScriptRunner, which owns
- * execution tracking, error recording, and status updates.
+ * Handle an EventBridge Scheduler direct invoke: the event itself is a single
+ * execution message (no `Records` wrapper).
+ * @param {Object} event - The execution message.
+ * @param {{ scriptFactory: ScriptFactory, integrationFactory: object }} deps
+ * @returns {Promise<{ statusCode: number, body: string }>}
+ * @private
  */
-async function handler(event) {
-    const { integrationFactory } = bootstrapAdminScripts();
-
-    // EventBridge Scheduler invokes the Lambda directly (no Records wrapper)
-    if (!event.Records) {
-        try {
-            const result = await runMessage(event, integrationFactory);
-            console.log(
-                `Script completed: ${result.scriptName}, status: ${result.status}`
-            );
-            return {
-                statusCode: 200,
-                body: JSON.stringify({ processed: 1, results: [result] }),
-            };
-        } catch (error) {
-            console.error(
-                'Unexpected error processing scheduled invoke:',
-                error
-            );
-            await markFailed(event.executionId, error);
-            return {
-                statusCode: 200,
-                body: JSON.stringify({
-                    processed: 1,
-                    results: [
-                        {
-                            scriptName: event.scriptName || 'unknown',
-                            status: 'FAILED',
-                            error: error.message,
-                        },
-                    ],
-                }),
-            };
-        }
+async function handleScheduledInvoke(event, deps) {
+    try {
+        const result = await runMessage(event, deps);
+        console.log(
+            `Script completed: ${result.scriptName}, status: ${result.status}`
+        );
+        return {
+            statusCode: 200,
+            body: JSON.stringify({ processed: 1, results: [result] }),
+        };
+    } catch (error) {
+        console.error('Unexpected error processing scheduled invoke:', error);
+        await markFailed(event.executionId, error);
+        return {
+            statusCode: 200,
+            body: JSON.stringify({
+                processed: 1,
+                results: [
+                    {
+                        scriptName: event.scriptName || 'unknown',
+                        status: 'FAILED',
+                        error: error.message,
+                    },
+                ],
+            }),
+        };
     }
+}
 
+/**
+ * Handle an SQS batch: each `event.Records[].body` is a JSON execution message
+ * (manual async executions and queueScript continuations). Failures are isolated
+ * per record so one bad message doesn't drop the rest of the batch.
+ * @param {Object} event - The SQS event with a `Records` array.
+ * @param {{ scriptFactory: ScriptFactory, integrationFactory: object }} deps
+ * @returns {Promise<{ statusCode: number, body: string }>}
+ * @private
+ */
+async function handleSqsBatch(event, deps) {
     const results = [];
     for (const record of event.Records) {
         let message = {};
         try {
             message = JSON.parse(record.body);
-            const result = await runMessage(message, integrationFactory);
+            const result = await runMessage(message, deps);
             console.log(
                 `Script completed: ${result.scriptName}, status: ${result.status}`
             );
@@ -143,4 +153,24 @@ async function handler(event) {
     };
 }
 
+/**
+ * Admin Script Executor Lambda Handler
+ *
+ * Handles two invocation shapes:
+ * - SQS: `event.Records[]` — each record body is a JSON execution message
+ *   (manual async executions and queueScript continuations).
+ * - EventBridge Scheduler direct invoke: the event itself is the message
+ *   (`{ scriptName, trigger: 'SCHEDULED', params }`) with no `Records` wrapper.
+ *
+ * Thin adapter: parses the event and delegates to ScriptRunner, which owns
+ * execution tracking, error recording, and status updates.
+ */
+async function handler(event) {
+    const deps = bootstrapAdminScripts();
+
+    return event.Records
+        ? handleSqsBatch(event, deps)
+        : handleScheduledInvoke(event, deps);
+}
+
 module.exports = { handler };