@friggframework/admin-scripts 2.0.0--canary.545.b4ca16d.0 → 2.0.0--canary.517.8eaf5df.0

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

@@ -3,10 +3,18 @@ const serverless = require('serverless-http');
 const { validateAdminApiKey } = require('./admin-auth-middleware');
 const { getScriptFactory } = require('../application/script-factory');
 const { createScriptRunner } = require('../application/script-runner');
-const { validateScriptInput } = require('../application/validate-script-input');
-const { createAdminScriptCommands } = require('@friggframework/core/application/commands/admin-script-commands');
+const {
+    validateScriptInput,
+    validateParams,
+} = require('../application/validate-script-input');
+const {
+    createAdminScriptCommands,
+} = require('@friggframework/core/application/commands/admin-script-commands');
 const { QueuerUtil } = require('@friggframework/core/queues');
-const { createSchedulerAdapter } = require('../adapters/scheduler-adapter-factory');
+const {
+    createSchedulerAdapter,
+} = require('../adapters/scheduler-adapter-factory');
+const { bootstrapAdminScripts } = require('./bootstrap');
 const {
     GetEffectiveScheduleUseCase,
     UpsertScheduleUseCase,
@@ -18,14 +26,51 @@ const router = express.Router();
 // Apply auth middleware to all admin routes
 router.use(validateAdminApiKey);
 
+// Register the host app's admin scripts (and built-ins) before handling requests.
+// Memoized, so this only does work on the first request per process.
+router.use((_req, _res, next) => {
+    bootstrapAdminScripts();
+    next();
+});
+
+/**
+ * Build audit metadata for an execution from the request.
+ * @private
+ */
+function buildAudit(req) {
+    const apiKey = req.headers['x-frigg-admin-api-key'];
+    const forwardedFor = (req.headers['x-forwarded-for'] || '')
+        .split(',')[0]
+        .trim();
+    return {
+        ipAddress: forwardedFor || req.ip || null,
+        apiKeyLast4: apiKey ? String(apiKey).slice(-4) : null,
+    };
+}
+
 /**
  * Create schedule use case instances
  * @private
  */
 function createScheduleUseCases() {
     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) {
+        const error = new Error(
+            'SCHEDULER_PROVIDER is not configured. Set it (e.g. "aws") via appDefinition.admin.enableScheduling.'
+        );
+        error.code = 'SCHEDULER_NOT_CONFIGURED';
+        throw error;
+    }
+
     const schedulerAdapter = createSchedulerAdapter({
-        type: process.env.SCHEDULER_PROVIDER || 'local',
+        type: schedulerType,
         targetLambdaArn: process.env.ADMIN_SCRIPT_EXECUTOR_LAMBDA_ARN,
         scheduleGroupName: process.env.ADMIN_SCRIPT_SCHEDULE_GROUP,
         roleArn: process.env.SCHEDULER_ROLE_ARN,
@@ -33,9 +78,20 @@ function createScheduleUseCases() {
     const scriptFactory = getScriptFactory();
 
     return {
-        getEffectiveSchedule: new GetEffectiveScheduleUseCase({ commands, scriptFactory }),
-        upsertSchedule: new UpsertScheduleUseCase({ commands, schedulerAdapter, scriptFactory }),
-        deleteSchedule: new DeleteScheduleUseCase({ commands, schedulerAdapter, scriptFactory }),
+        getEffectiveSchedule: new GetEffectiveScheduleUseCase({
+            commands,
+            scriptFactory,
+        }),
+        upsertSchedule: new UpsertScheduleUseCase({
+            commands,
+            schedulerAdapter,
+            scriptFactory,
+        }),
+        deleteSchedule: new DeleteScheduleUseCase({
+            commands,
+            schedulerAdapter,
+            scriptFactory,
+        }),
     };
 }
 
@@ -142,11 +198,40 @@ router.post('/scripts/:scriptName', async (req, res) => {
             });
         }
 
+        const definition = factory.get(scriptName).Definition;
+
+        // Fail fast on invalid input instead of starting an execution that will error
+        const validation = validateParams(definition, params);
+        if (!validation.valid) {
+            return res.status(400).json({
+                error: `Invalid input: ${validation.errors.join(', ')}`,
+                code: 'INVALID_INPUT',
+                details: validation.errors,
+            });
+        }
+
+        const audit = buildAudit(req);
+
         if (mode === 'sync') {
-            const runner = createScriptRunner();
+            // Sync runs inside the 30s API Lambda; long scripts must use async
+            const timeout = definition.config?.timeout;
+            if (
+                process.env.AWS_LAMBDA_FUNCTION_NAME &&
+                timeout &&
+                timeout > 25000
+            ) {
+                return res.status(400).json({
+                    error: `Script "${scriptName}" timeout (${timeout}ms) exceeds the sync API limit. Use mode: "async".`,
+                    code: 'SYNC_TIMEOUT_TOO_LONG',
+                });
+            }
+
+            const { integrationFactory } = bootstrapAdminScripts();
+            const runner = createScriptRunner({ integrationFactory });
             const result = await runner.execute(scriptName, params, {
                 trigger: 'MANUAL',
                 mode: 'sync',
+                audit,
             });
             return res.json(result);
         }
@@ -163,12 +248,21 @@ router.post('/scripts/:scriptName', async (req, res) => {
         const commands = createAdminScriptCommands();
         const execution = await commands.createAdminProcess({
             scriptName,
-            scriptVersion: factory.get(scriptName).Definition.version,
+            scriptVersion: definition.version,
             trigger: 'MANUAL',
             mode: 'async',
             input: params,
+            audit,
         });
 
+        // Commands return an error object (never throw) — don't queue a broken execution
+        if (execution.error) {
+            return res.status(execution.error).json({
+                error: execution.reason || 'Failed to create execution record',
+                code: execution.code,
+            });
+        }
+
         // Queue the execution
         await QueuerUtil.send(
             {
@@ -226,10 +320,14 @@ router.get('/scripts/:scriptName/executions', async (req, res) => {
         const { status, limit = 50 } = req.query;
         const commands = createAdminScriptCommands();
 
-        const executions = await commands.findRecentExecutions({
-            scriptName,
-            status,
-            limit: Number.parseInt(limit, 10),
+        const parsedLimit = Number.parseInt(limit, 10);
+        const safeLimit = Number.isNaN(parsedLimit)
+            ? 50
+            : Math.min(Math.max(parsedLimit, 1), 200);
+
+        const executions = await commands.findAdminProcessesByName(scriptName, {
+            limit: safeLimit,
+            ...(status && { state: status }),
         });
 
         res.json({ executions });
@@ -262,6 +360,11 @@ router.get('/scripts/:scriptName/schedule', async (req, res) => {
                 code: error.code,
             });
         }
+        if (error.code === 'SCHEDULER_NOT_CONFIGURED') {
+            return res
+                .status(503)
+                .json({ error: error.message, code: error.code });
+        }
         console.error('Error getting schedule:', error);
         res.status(500).json({ error: 'Failed to get schedule' });
     }
@@ -289,7 +392,9 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
                 source: 'database',
                 ...result.schedule,
             },
-            ...(result.schedulerWarning && { schedulerWarning: result.schedulerWarning }),
+            ...(result.schedulerWarning && {
+                schedulerWarning: result.schedulerWarning,
+            }),
         });
     } catch (error) {
         if (error.code === 'SCRIPT_NOT_FOUND') {
@@ -304,6 +409,11 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
                 code: error.code,
             });
         }
+        if (error.code === 'SCHEDULER_NOT_CONFIGURED') {
+            return res
+                .status(503)
+                .json({ error: error.message, code: error.code });
+        }
         console.error('Error updating schedule:', error);
         res.status(500).json({ error: 'Failed to update schedule' });
     }
@@ -328,6 +438,11 @@ router.delete('/scripts/:scriptName/schedule', async (req, res) => {
                 code: error.code,
             });
         }
+        if (error.code === 'SCHEDULER_NOT_CONFIGURED') {
+            return res
+                .status(503)
+                .json({ error: error.message, code: error.code });
+        }
         console.error('Error deleting schedule:', error);
         res.status(500).json({ error: 'Failed to delete schedule' });
     }

package/src/infrastructure/bootstrap.js

@@ -0,0 +1,87 @@
+const { getScriptFactory } = 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.
+ *
+ * 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 integrationFactory = null;
+
+function registerScripts(factory, scriptClasses) {
+    for (const ScriptClass of scriptClasses || []) {
+        const name = ScriptClass?.Definition?.name;
+        // Guard against re-registration (register() throws on name collision)
+        if (name && !factory.has(name)) {
+            factory.register(ScriptClass);
+        }
+    }
+}
+
+/**
+ * Build an integration factory backed by the framework's runtime hydration.
+ * Scripts call `context.instantiate(integrationId)` which delegates here.
+ * The require is lazy so the admin-scripts package has no load-time coupling
+ * to core's backend utilities (and unit tests never hit this path).
+ */
+function createIntegrationFactory() {
+    return {
+        async getInstanceFromIntegrationId({ integrationId }) {
+            const {
+                loadIntegrationForWebhook,
+            } = require('@friggframework/core/handlers/backend-utils');
+            return loadIntegrationForWebhook(integrationId);
+        },
+    };
+}
+
+/**
+ * @returns {{ integrationFactory: object }}
+ */
+function bootstrapAdminScripts() {
+    if (bootstrapped) {
+        return { integrationFactory };
+    }
+    bootstrapped = true;
+
+    try {
+        const {
+            loadAppDefinition,
+        } = require('@friggframework/core/handlers/app-definition-loader');
+        const { adminScripts = [], admin = {} } = loadAppDefinition();
+
+        const factory = getScriptFactory();
+        registerScripts(factory, adminScripts);
+
+        if (admin.includeBuiltinScripts) {
+            const { builtinScripts } = require('../builtins');
+            registerScripts(factory, builtinScripts);
+        }
+    } catch (error) {
+        console.error(
+            '[admin-scripts] bootstrap: could not load app definition:',
+            error.message
+        );
+    }
+
+    integrationFactory = createIntegrationFactory();
+    return { integrationFactory };
+}
+
+/** Test-only: reset memoized bootstrap state. */
+function _resetBootstrapForTests() {
+    bootstrapped = false;
+    integrationFactory = null;
+}
+
+module.exports = {
+    bootstrapAdminScripts,
+    _resetBootstrapForTests,
+};

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

@@ -1,69 +1,136 @@
 const { createScriptRunner } = require('../application/script-runner');
-const { createAdminScriptCommands } = require('@friggframework/core/application/commands/admin-script-commands');
+const {
+    createAdminScriptCommands,
+} = require('@friggframework/core/application/commands/admin-script-commands');
+const { bootstrapAdminScripts } = require('./bootstrap');
 
 /**
- * SQS Queue Worker Lambda Handler
- *
- * Processes script execution messages from AdminScriptQueue.
- * Thin adapter: parses SQS messages and delegates to ScriptRunner.
- * ScriptRunner handles execution tracking, error recording, and status updates.
+ * Run a single execution message through the ScriptRunner.
+ * @private
  */
-async function handler(event) {
-    const results = [];
+async function runMessage(message, integrationFactory) {
+    const { scriptName, executionId, trigger, params, parentExecutionId } =
+        message;
 
-    for (const record of event.Records) {
-        let scriptName;
-        let executionId;
+    if (!scriptName) {
+        throw new Error('Invalid message: missing scriptName');
+    }
 
-        try {
-            const message = JSON.parse(record.body);
-            ({ scriptName, executionId } = message);
-            const { trigger, params } = message;
+    console.log(
+        `Processing script: ${scriptName}${
+            executionId ? `, executionId: ${executionId}` : ''
+        }`
+    );
 
-            if (!scriptName || !executionId) {
-                throw new Error(`Invalid SQS message: missing scriptName or executionId`);
-            }
+    const runner = createScriptRunner({ integrationFactory });
+    const result = await runner.execute(scriptName, params, {
+        trigger: trigger || 'QUEUE',
+        mode: 'async',
+        // executionId is optional — when absent, ScriptRunner creates the record.
+        // Scheduled direct invokes and queueScript continuations have no id yet.
+        ...(executionId && { executionId }),
+        ...(parentExecutionId && { parentExecutionId }),
+    });
 
-            console.log(`Processing script: ${scriptName}, executionId: ${executionId}`);
+    return {
+        scriptName,
+        status: result.status,
+        executionId: result.executionId,
+    };
+}
 
-            const runner = createScriptRunner();
-            const result = await runner.execute(scriptName, params, {
-                trigger: trigger || 'QUEUE',
-                mode: 'async',
-                executionId,
-            });
+/**
+ * Mark an admin process FAILED when the worker itself blows up (parse error,
+ * runner construction), so the record doesn't stay stuck in a non-terminal
+ * state. No-op when there is no execution id.
+ * @private
+ */
+async function markFailed(executionId, error) {
+    if (!executionId) return;
+    try {
+        const commands = createAdminScriptCommands();
+        await commands.completeAdminProcess(executionId, {
+            state: 'FAILED',
+            error: {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            },
+        });
+    } catch (updateError) {
+        console.error(
+            `Failed to update execution ${executionId} state:`,
+            updateError
+        );
+    }
+}
 
-            console.log(`Script completed: ${scriptName}, status: ${result.status}`);
-            results.push({
-                scriptName,
-                status: result.status,
-                executionId: result.executionId,
-            });
-        } catch (error) {
-            // Only reaches here for unexpected failures (message parse errors, runner construction).
-            // Script execution errors are handled by ScriptRunner and returned as { status: 'FAILED' }.
-            console.error(`Unexpected error processing record:`, 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.
+ */
+async function handler(event) {
+    const { integrationFactory } = bootstrapAdminScripts();
 
-            // If we have an executionId, mark the admin process as FAILED
-            // so the record doesn't stay stuck in a non-terminal state.
-            if (executionId) {
-                try {
-                    const commands = createAdminScriptCommands();
-                    await commands.completeAdminProcess(executionId, {
-                        state: 'FAILED',
-                        error: {
-                            name: error.name,
-                            message: error.message,
-                            stack: error.stack,
+    // 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,
                         },
-                    });
-                } catch (updateError) {
-                    console.error(`Failed to update execution ${executionId} state:`, updateError);
-                }
-            }
+                    ],
+                }),
+            };
+        }
+    }
 
+    const results = [];
+    for (const record of event.Records) {
+        let message = {};
+        try {
+            message = JSON.parse(record.body);
+            const result = await runMessage(message, integrationFactory);
+            console.log(
+                `Script completed: ${result.scriptName}, status: ${result.status}`
+            );
+            results.push(result);
+        } catch (error) {
+            // Only unexpected failures reach here (message parse errors, runner
+            // construction). Script execution errors are handled by ScriptRunner
+            // and returned as { status: 'FAILED' }.
+            console.error('Unexpected error processing record:', error);
+            await markFailed(message.executionId, error);
             results.push({
-                scriptName: scriptName || 'unknown',
+                scriptName: message.scriptName || 'unknown',
                 status: 'FAILED',
                 error: error.message,
             });