@friggframework/admin-scripts 2.0.0--canary.517.06fe141.0 → 2.0.0--canary.517.a353e20.0

package/README.md

@@ -6,7 +6,7 @@ Typical use cases:
 
 -   **Healing scripts** — repair broken integration state (e.g. corrupted config).
 -   **Recurring maintenance** — refresh webhooks/subscriptions before they expire.
--   **Built-in utilities** — OAuth token refresh, integration health checks.
+-   **Operational tasks** — OAuth token refresh, integration health checks, one-off data backfills. (You write these — none ship built-in.)
 
 > Admin scripts are a **high-privilege** surface. Every endpoint is protected by an admin API key (`x-frigg-admin-api-key`), scripts run in your private VPC subnets, and every execution is tracked in the `AdminScriptExecution` table. Never expose the admin API key to browsers or end users.
 

package/package.json

@@ -1,19 +1,19 @@
 {
     "name": "@friggframework/admin-scripts",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.517.06fe141.0",
+    "version": "2.0.0--canary.517.a353e20.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.06fe141.0",
+        "@friggframework/core": "2.0.0--canary.517.a353e20.0",
         "@hapi/boom": "^10.0.1",
         "express": "^4.18.2",
         "serverless-http": "^3.2.0"
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.517.06fe141.0",
-        "@friggframework/prettier-config": "2.0.0--canary.517.06fe141.0",
-        "@friggframework/test": "2.0.0--canary.517.06fe141.0",
+        "@friggframework/eslint-config": "2.0.0--canary.517.a353e20.0",
+        "@friggframework/prettier-config": "2.0.0--canary.517.a353e20.0",
+        "@friggframework/test": "2.0.0--canary.517.a353e20.0",
         "eslint": "^8.22.0",
         "jest": "^29.7.0",
         "prettier": "^2.7.1",
@@ -44,5 +44,5 @@
         "maintenance",
         "operations"
     ],
-    "gitHead": "06fe14103a72028ce7bf622631580fb24a4abaaf"
+    "gitHead": "a353e204564567f210a23149f4fa7fdb6d779d72"
 }

package/src/adapters/__tests__/scheduler-adapter-factory.test.js

@@ -1,4 +1,7 @@
-const { createSchedulerAdapter } = require('../scheduler-adapter-factory');
+const {
+    createSchedulerAdapter,
+    createSchedulerAdapterFromEnv,
+} = require('../scheduler-adapter-factory');
 const { AWSSchedulerAdapter } = require('../aws-scheduler-adapter');
 const { LocalSchedulerAdapter } = require('../local-scheduler-adapter');
 
@@ -135,4 +138,51 @@ describe('Scheduler Adapter Factory', () => {
             ).toThrow();
         });
     });
+
+    describe('createSchedulerAdapterFromEnv()', () => {
+        it('falls back to the local adapter off-AWS when SCHEDULER_PROVIDER is unset', () => {
+            delete process.env.SCHEDULER_PROVIDER;
+            delete process.env.AWS_LAMBDA_FUNCTION_NAME;
+
+            const adapter = createSchedulerAdapterFromEnv();
+
+            expect(adapter).toBeInstanceOf(LocalSchedulerAdapter);
+        });
+
+        it('throws 503 when SCHEDULER_PROVIDER is unset in a deployed Lambda', () => {
+            delete process.env.SCHEDULER_PROVIDER;
+            process.env.AWS_LAMBDA_FUNCTION_NAME = 'admin-script-router';
+
+            let error;
+            try {
+                createSchedulerAdapterFromEnv();
+            } catch (e) {
+                error = e;
+            }
+
+            expect(error).toBeDefined();
+            expect(error.isBoom).toBe(true);
+            expect(error.output.statusCode).toBe(503);
+        });
+
+        it('builds the AWS adapter from SCHEDULER_PROVIDER + ADMIN_SCRIPT_* env', () => {
+            process.env.SCHEDULER_PROVIDER = 'aws';
+            process.env.ADMIN_SCRIPT_EXECUTOR_LAMBDA_ARN =
+                awsAdapterParams.targetLambdaArn;
+            process.env.ADMIN_SCRIPT_SCHEDULE_GROUP =
+                awsAdapterParams.scheduleGroupName;
+            process.env.SCHEDULER_ROLE_ARN = awsAdapterParams.roleArn;
+
+            const adapter = createSchedulerAdapterFromEnv();
+
+            expect(adapter).toBeInstanceOf(AWSSchedulerAdapter);
+            expect(adapter.targetLambdaArn).toBe(
+                awsAdapterParams.targetLambdaArn
+            );
+            expect(adapter.scheduleGroupName).toBe(
+                awsAdapterParams.scheduleGroupName
+            );
+            expect(adapter.roleArn).toBe(awsAdapterParams.roleArn);
+        });
+    });
 });

package/src/adapters/scheduler-adapter-factory.js

@@ -1,13 +1,16 @@
+const Boom = require('@hapi/boom');
 const { AWSSchedulerAdapter } = require('./aws-scheduler-adapter');
 const { LocalSchedulerAdapter } = require('./local-scheduler-adapter');
 
 /**
  * Scheduler Adapter Factory
  *
- * Application Layer - Hexagonal Architecture
+ * Infrastructure Layer - Hexagonal Architecture
  *
- * Creates the appropriate scheduler adapter based on explicit configuration
- * from appDefinition. Does not auto-detect or read environment variables.
+ * `createSchedulerAdapter` builds an adapter from an explicit `type` (no env
+ * reads). `createSchedulerAdapterFromEnv` resolves the type from the runtime
+ * environment and enforces that a deployed Lambda never silently falls back to
+ * the in-memory local adapter.
  */
 
 /**
@@ -46,6 +49,37 @@ function createSchedulerAdapter(options = {}) {
     }
 }
 
+/**
+ * Resolve and build the scheduler adapter from the runtime environment.
+ *
+ * The local adapter is in-memory only (schedules vanish on cold start), so it
+ * must never be the silent default in a deployed Lambda: require an explicit
+ * SCHEDULER_PROVIDER when running on AWS, and fall back to 'local' only for
+ * local dev/tests.
+ *
+ * @returns {SchedulerAdapter}
+ * @throws {Boom.Boom} 503 (serverUnavailable) when SCHEDULER_PROVIDER is unset
+ *   in a deployed Lambda.
+ */
+function createSchedulerAdapterFromEnv() {
+    const type =
+        process.env.SCHEDULER_PROVIDER ||
+        (process.env.AWS_LAMBDA_FUNCTION_NAME ? null : 'local');
+    if (!type) {
+        throw Boom.serverUnavailable(
+            'SCHEDULER_PROVIDER is not configured. Set it (e.g. "aws") via appDefinition.admin.enableScheduling.'
+        );
+    }
+
+    return createSchedulerAdapter({
+        type,
+        targetLambdaArn: process.env.ADMIN_SCRIPT_EXECUTOR_LAMBDA_ARN,
+        scheduleGroupName: process.env.ADMIN_SCRIPT_SCHEDULE_GROUP,
+        roleArn: process.env.SCHEDULER_ROLE_ARN,
+    });
+}
+
 module.exports = {
     createSchedulerAdapter,
+    createSchedulerAdapterFromEnv,
 };

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

@@ -111,27 +111,8 @@ describe('AdminScriptContext', () => {
                 mockFactory.getInstanceFromIntegrationId
             ).toHaveBeenCalledWith({
                 integrationId: 'int_123',
-                _isAdminContext: true,
             });
         });
-
-        it('passes _isAdminContext: true', async () => {
-            const mockInstance = { primary: { api: {} } };
-            const mockFactory = {
-                getInstanceFromIntegrationId: jest
-                    .fn()
-                    .mockResolvedValue(mockInstance),
-            };
-            const ctx = new AdminScriptContext({
-                integrationFactory: mockFactory,
-            });
-
-            await ctx.instantiate('int_123');
-
-            const callArgs =
-                mockFactory.getInstanceFromIntegrationId.mock.calls[0][0];
-            expect(callArgs._isAdminContext).toBe(true);
-        });
     });
 
     describe('queueScript()', () => {

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

@@ -11,8 +11,8 @@ const { QueuerUtil } = require('@friggframework/core/queues');
  *   `commands.entities`, and `commands.integrations` expose the framework's
  *   command layer. Each command returns data on success or an `{ error }`
  *   object on failure — scripts check `.error` themselves.
- * - **Admin bypass**: `instantiate()` passes `_isAdminContext: true` to
- *   skip user-ownership checks when loading integration instances
+ * - **Integration instantiation**: `instantiate(integrationId)` hydrates a live
+ *   integration instance (system-scoped load) for calling external APIs
  * - **Script chaining**: `queueScript()` / `queueScriptBatch()` let scripts
  *   enqueue follow-up work with parent execution tracking
  * - **Execution-scoped logging**: `log()` collects structured entries tied
@@ -52,7 +52,6 @@ class AdminScriptContext {
         }
         return this.integrationFactory.getInstanceFromIntegrationId({
             integrationId,
-            _isAdminContext: true, // Bypass user ownership check
         });
     }
 

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

@@ -23,7 +23,7 @@ const {
 } = require('@friggframework/core/application/commands/admin-script-commands');
 const { QueuerUtil } = require('@friggframework/core/queues');
 const {
-    createSchedulerAdapter,
+    createSchedulerAdapterFromEnv,
 } = require('../../adapters/scheduler-adapter-factory');
 
 describe('Admin Script Router', () => {
@@ -76,7 +76,7 @@ describe('Admin Script Router', () => {
         });
         createScriptRunner.mockReturnValue(mockRunner);
         createAdminScriptCommands.mockReturnValue(mockCommands);
-        createSchedulerAdapter.mockReturnValue(mockSchedulerAdapter);
+        createSchedulerAdapterFromEnv.mockReturnValue(mockSchedulerAdapter);
         QueuerUtil.send = jest.fn().mockResolvedValue({});
 
         // Default mock implementations
@@ -253,6 +253,70 @@ describe('Admin Script Router', () => {
             expect(response.status).toBe(404);
             expect(response.body.code).toBe('SCRIPT_NOT_FOUND');
         });
+
+        it('rejects a sync script whose timeout exceeds the API budget on AWS', async () => {
+            // TestScript.Definition.config.timeout is 300000 (> 25000)
+            process.env.AWS_LAMBDA_FUNCTION_NAME = 'admin-script-router';
+
+            const response = await request(app)
+                .post('/admin/scripts/test-script')
+                .send({ params: {}, mode: 'sync' });
+
+            expect(response.status).toBe(400);
+            expect(response.body.code).toBe('SYNC_TIMEOUT_TOO_LONG');
+            expect(mockRunner.execute).not.toHaveBeenCalled();
+            delete process.env.AWS_LAMBDA_FUNCTION_NAME;
+        });
+
+        it('allows a sync script within the budget on AWS (25000 boundary)', async () => {
+            process.env.AWS_LAMBDA_FUNCTION_NAME = 'admin-script-router';
+            class ShortScript extends AdminScriptBase {
+                static Definition = {
+                    name: 'short-script',
+                    version: '1.0.0',
+                    description: 'within budget',
+                    config: { timeout: 25000 },
+                };
+                async execute() {
+                    return {};
+                }
+            }
+            mockFactory.get.mockReturnValue(ShortScript);
+            mockRunner.execute.mockResolvedValue({
+                executionId: 'exec-1',
+                status: 'COMPLETED',
+                scriptName: 'short-script',
+                output: {},
+                metrics: { durationMs: 1 },
+            });
+
+            const response = await request(app)
+                .post('/admin/scripts/short-script')
+                .send({ params: {}, mode: 'sync' });
+
+            expect(response.status).toBe(200);
+            expect(mockRunner.execute).toHaveBeenCalled();
+            delete process.env.AWS_LAMBDA_FUNCTION_NAME;
+        });
+
+        it('does not queue and surfaces the error when createExecution fails (async)', async () => {
+            process.env.ADMIN_SCRIPT_QUEUE_URL =
+                'https://sqs.us-east-1.amazonaws.com/123/test-queue';
+            mockCommands.createExecution.mockResolvedValue({
+                error: 500,
+                reason: 'DB down',
+                code: 'DB_ERROR',
+            });
+
+            const response = await request(app)
+                .post('/admin/scripts/test-script')
+                .send({ params: { foo: 'bar' }, mode: 'async' });
+
+            expect(response.status).toBe(500);
+            expect(response.body.error).toBe('DB down');
+            expect(QueuerUtil.send).not.toHaveBeenCalled();
+            delete process.env.ADMIN_SCRIPT_QUEUE_URL;
+        });
     });
 
     describe('GET /admin/scripts/:scriptName/executions/:executionId', () => {

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

@@ -1,6 +1,5 @@
 const express = require('express');
 const serverless = require('serverless-http');
-const Boom = require('@hapi/boom');
 const { validateAdminApiKey } = require('./admin-auth-middleware');
 const { createScriptRunner } = require('../application/script-runner');
 const {
@@ -12,7 +11,7 @@ const {
 } = require('@friggframework/core/application/commands/admin-script-commands');
 const { QueuerUtil } = require('@friggframework/core/queues');
 const {
-    createSchedulerAdapter,
+    createSchedulerAdapterFromEnv,
 } = require('../adapters/scheduler-adapter-factory');
 const { bootstrapAdminScripts } = require('./bootstrap');
 const {
@@ -60,51 +59,6 @@ function buildAudit(req) {
     };
 }
 
-/**
- * Create schedule use case instances
- * @param {ScriptFactory} scriptFactory - Registry injected from the request.
- * @private
- */
-function createScheduleUseCases(scriptFactory) {
-    const commands = createAdminScriptCommands();
-
-    // The local adapter is in-memory only (schedules vanish on cold start), so it
-    // must never be the silent default in a deployed Lambda. Require an explicit
-    // provider when running on AWS; fall back to 'local' only for local dev/tests.
-    const schedulerType =
-        process.env.SCHEDULER_PROVIDER ||
-        (process.env.AWS_LAMBDA_FUNCTION_NAME ? null : 'local');
-    if (!schedulerType) {
-        throw Boom.serverUnavailable(
-            'SCHEDULER_PROVIDER is not configured. Set it (e.g. "aws") via appDefinition.admin.enableScheduling.'
-        );
-    }
-
-    const schedulerAdapter = createSchedulerAdapter({
-        type: schedulerType,
-        targetLambdaArn: process.env.ADMIN_SCRIPT_EXECUTOR_LAMBDA_ARN,
-        scheduleGroupName: process.env.ADMIN_SCRIPT_SCHEDULE_GROUP,
-        roleArn: process.env.SCHEDULER_ROLE_ARN,
-    });
-
-    return {
-        getEffectiveSchedule: new GetEffectiveScheduleUseCase({
-            commands,
-            scriptFactory,
-        }),
-        upsertSchedule: new UpsertScheduleUseCase({
-            commands,
-            schedulerAdapter,
-            scriptFactory,
-        }),
-        deleteSchedule: new DeleteScheduleUseCase({
-            commands,
-            schedulerAdapter,
-            scriptFactory,
-        }),
-    };
-}
-
 /**
  * GET /admin/scripts
  * List all registered scripts
@@ -354,13 +308,17 @@ router.get('/scripts/:scriptName/executions', async (req, res) => {
 
 /**
  * GET /admin/scripts/:scriptName/schedule
- * Get effective schedule (DB override > Definition default > none)
+ * Get the effective schedule (the DB override, or none)
  */
 router.get('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
         const { scriptFactory } = bootstrapAdminScripts();
-        const { getEffectiveSchedule } = createScheduleUseCases(scriptFactory);
+        const commands = createAdminScriptCommands();
+        const getEffectiveSchedule = new GetEffectiveScheduleUseCase({
+            commands,
+            scriptFactory,
+        });
 
         const result = await getEffectiveSchedule.execute(scriptName);
 
@@ -383,7 +341,13 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
         const { scriptName } = req.params;
         const { enabled, cronExpression, timezone } = req.body;
         const { scriptFactory } = bootstrapAdminScripts();
-        const { upsertSchedule } = createScheduleUseCases(scriptFactory);
+        const commands = createAdminScriptCommands();
+        const schedulerAdapter = createSchedulerAdapterFromEnv();
+        const upsertSchedule = new UpsertScheduleUseCase({
+            commands,
+            schedulerAdapter,
+            scriptFactory,
+        });
 
         const result = await upsertSchedule.execute(scriptName, {
             enabled,
@@ -408,13 +372,19 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
 
 /**
  * DELETE /admin/scripts/:scriptName/schedule
- * Remove schedule override (revert to Definition default)
+ * Remove the schedule override
  */
 router.delete('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
         const { scriptFactory } = bootstrapAdminScripts();
-        const { deleteSchedule } = createScheduleUseCases(scriptFactory);
+        const commands = createAdminScriptCommands();
+        const schedulerAdapter = createSchedulerAdapterFromEnv();
+        const deleteSchedule = new DeleteScheduleUseCase({
+            commands,
+            schedulerAdapter,
+            scriptFactory,
+        });
 
         const result = await deleteSchedule.execute(scriptName);