@friggframework/admin-scripts 2.0.0-next.103 → 2.0.0-next.105

package/src/infrastructure/bootstrap.js

@@ -1,22 +1,26 @@
 const { ScriptFactory } = require('../application/script-factory');
 
 /**
- * Admin Script Bootstrap
+ * Admin Operations Bootstrap
  *
  * 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.
+ * definition at Lambda runtime and builds two name-keyed registries — one for
+ * admin scripts, one for reports — plus the command bundles they need, so the
+ * routers and SQS workers can resolve operations by name. The registry class is
+ * shared (ScriptFactory is generic over `static Definition.name`); reports are a
+ * second instance rather than a duplicate class.
  *
  * Runs once per process (memoized) and never throws — a missing/unloadable app
- * definition is logged and leaves the factory empty rather than crashing the
+ * definition is logged and leaves the registries empty rather than crashing the
  * Lambda cold start.
  */
 let bootstrapped = false;
 let scriptFactory = null;
 let scriptCommands = null;
 let integrationFactory = null;
+let reportFactory = null;
+let reportCommands = null;
+let reportFriggCommands = null;
 
 function registerScripts(factory, scriptClasses) {
     for (const ScriptClass of scriptClasses || []) {
@@ -28,6 +32,24 @@ function registerScripts(factory, scriptClasses) {
     }
 }
 
+// A report whose name collides with a registered script is skipped: scripts and
+// reports share ScriptSchedule.scriptName (@unique), so names must not clash.
+function registerReports(factory, scriptRegistry, reportClasses) {
+    for (const ReportClass of reportClasses || []) {
+        const name = ReportClass?.Definition?.name;
+        if (!name) continue;
+        if (scriptRegistry.has(name)) {
+            console.error(
+                `[admin-scripts] bootstrap: report "${name}" collides with a registered script name; skipping.`
+            );
+            continue;
+        }
+        if (!factory.has(name)) {
+            factory.register(ReportClass);
+        }
+    }
+}
+
 /**
  * Build an integration factory backed by the framework's runtime hydration.
  * Scripts call `context.instantiate(integrationId)` which delegates here.
@@ -46,7 +68,7 @@ function createIntegrationFactory() {
 }
 
 /**
- * Build the command bundle injected into every AdminScriptContext. Scripts
+ * Build the command bundle injected into every AdminScriptContext. Operations
  * interact with the database only through these Frigg commands — never through
  * repositories directly. The require is lazy so the package keeps no load-time
  * coupling to core's command/repository modules.
@@ -75,27 +97,62 @@ function buildScriptCommands() {
     };
 }
 
+function buildReportFriggCommands() {
+    const {
+        createIntegrationMappingCommands,
+    } = require('@friggframework/core/application/commands/integration-mapping-commands');
+    const {
+        createUsageCommands,
+    } = require('@friggframework/core/application/commands/usage-commands');
+
+    return {
+        ...buildScriptCommands(),
+        integrationMappings: createIntegrationMappingCommands(),
+        usage: createUsageCommands(),
+    };
+}
+
 /**
- * @returns {{ scriptFactory: ScriptFactory, scriptCommands: object, integrationFactory: object }}
+ * @returns {{ scriptFactory: ScriptFactory, scriptCommands: object, integrationFactory: object, reportFactory: ScriptFactory, reportCommands: object, reportFriggCommands: object }}
  */
 function bootstrapAdminScripts() {
     if (bootstrapped) {
-        return { scriptFactory, scriptCommands, integrationFactory };
+        return {
+            scriptFactory,
+            scriptCommands,
+            integrationFactory,
+            reportFactory,
+            reportCommands,
+            reportFriggCommands,
+        };
     }
     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
+    // Create the registries up front so consumers always get (possibly empty)
+    // factories even when the app definition can't be loaded — mirrors the
     // never-throw contract above.
     scriptFactory = new ScriptFactory();
+    reportFactory = new ScriptFactory();
 
     try {
         const {
             loadAppDefinition,
         } = require('@friggframework/core/handlers/app-definition-loader');
-        const { adminScripts = [] } = loadAppDefinition();
+        const {
+            adminScripts = [],
+            reports = [],
+            admin = {},
+        } = loadAppDefinition();
 
         registerScripts(scriptFactory, adminScripts);
+        registerReports(reportFactory, scriptFactory, reports);
+
+        if (admin.includeBuiltinReports) {
+            const {
+                BUILTIN_REPORTS,
+            } = require('@friggframework/core/reporting/builtin-reports');
+            registerReports(reportFactory, scriptFactory, BUILTIN_REPORTS);
+        }
     } catch (error) {
         console.error(
             '[admin-scripts] bootstrap: could not load app definition:',
@@ -103,8 +160,8 @@ function bootstrapAdminScripts() {
         );
     }
 
-    // Built in its own try so a command-layer failure never blocks script
-    // registration (and vice versa) — both honor the never-throw contract.
+    // Built in their own try so a command-layer failure never blocks operation
+    // registration (and vice versa) — all honor the never-throw contract.
     try {
         scriptCommands = buildScriptCommands();
     } catch (error) {
@@ -114,8 +171,28 @@ function bootstrapAdminScripts() {
         );
     }
 
+    try {
+        reportFriggCommands = buildReportFriggCommands();
+        const {
+            createReportCommands,
+        } = require('@friggframework/core/application/commands/report-commands');
+        reportCommands = createReportCommands();
+    } catch (error) {
+        console.error(
+            '[admin-scripts] bootstrap: could not build report commands:',
+            error.message
+        );
+    }
+
     integrationFactory = createIntegrationFactory();
-    return { scriptFactory, scriptCommands, integrationFactory };
+    return {
+        scriptFactory,
+        scriptCommands,
+        integrationFactory,
+        reportFactory,
+        reportCommands,
+        reportFriggCommands,
+    };
 }
 
 /** Test-only: reset memoized bootstrap state. */
@@ -124,6 +201,9 @@ function _resetBootstrapForTests() {
     scriptFactory = null;
     scriptCommands = null;
     integrationFactory = null;
+    reportFactory = null;
+    reportCommands = null;
+    reportFriggCommands = null;
 }
 
 module.exports = {

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

@@ -0,0 +1,202 @@
+const { createReportRunner } = require('../application/report-runner');
+const {
+    createReportCommands,
+} = require('@friggframework/core/application/commands/report-commands');
+const { QueuerUtil } = require('@friggframework/core/queues');
+const { bootstrapAdminScripts } = require('./bootstrap');
+
+// Resume state travels in the message (params.__resume); the execution record
+// stays RUNNING across hops so the same execution resumes.
+async function requeueContinuation(message, result) {
+    const queueUrl = process.env.REPORT_QUEUE_URL;
+    if (!queueUrl) {
+        throw new Error(
+            'Report yielded a continuation but REPORT_QUEUE_URL is not set; cannot resume'
+        );
+    }
+
+    await QueuerUtil.send(
+        {
+            reportName: message.reportName,
+            executionId: result.executionId,
+            mode: message.mode || 'recorded',
+            ...(message.seriesName && { seriesName: message.seriesName }),
+            trigger: 'QUEUE',
+            params: { ...(message.params || {}), __resume: result.continuation },
+            resumeAt: new Date().toISOString(),
+        },
+        queueUrl
+    );
+}
+
+async function runMessage(
+    message,
+    { reportFactory, reportCommands, reportFriggCommands, integrationFactory },
+    lambdaContext
+) {
+    const {
+        reportName,
+        executionId,
+        mode,
+        seriesName,
+        trigger,
+        params,
+        parentExecutionId,
+    } = message;
+
+    if (!reportName) {
+        throw new Error('Invalid message: missing reportName');
+    }
+
+    console.log(
+        `Processing report: ${reportName}${
+            executionId ? `, executionId: ${executionId}` : ''
+        }`
+    );
+
+    const runner = createReportRunner({
+        reportFactory,
+        reportCommands,
+        friggCommands: reportFriggCommands,
+        integrationFactory,
+    });
+    const result = await runner.execute(reportName, params, {
+        mode: mode || 'recorded',
+        trigger: trigger || 'QUEUE',
+        // Scheduled first runs carry no executionId; ReportRunner creates the record.
+        ...(executionId && { executionId }),
+        ...(seriesName && { seriesName }),
+        ...(parentExecutionId && { parentExecutionId }),
+        ...(lambdaContext && { lambdaContext }),
+    });
+
+    if (result.status === 'CONTINUE') {
+        // A failed re-enqueue means the execution never resumes; mark it FAILED
+        // (via the runner-created id) instead of leaving it stuck in RUNNING.
+        try {
+            await requeueContinuation(message, result);
+        } catch (requeueError) {
+            await markFailed(result.executionId, requeueError);
+            throw requeueError;
+        }
+        console.log(
+            `Report re-queued for continuation: ${reportName}, executionId: ${result.executionId}`
+        );
+    }
+
+    return {
+        reportName,
+        status: result.status,
+        executionId: result.executionId,
+    };
+}
+
+// Mark a report execution FAILED when the worker itself throws, so the record
+// doesn't stay stuck in a non-terminal state.
+async function markFailed(executionId, error) {
+    if (!executionId) return;
+    try {
+        const commands = createReportCommands();
+        await commands.completeExecution(executionId, {
+            state: 'FAILED',
+            error: {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            },
+        });
+    } catch (updateError) {
+        console.error(
+            `Failed to update report execution ${executionId} state:`,
+            updateError
+        );
+    }
+}
+
+// EventBridge Scheduler direct invoke: the event itself is the message (no `Records` wrapper).
+async function handleScheduledInvoke(event, deps, lambdaContext) {
+    try {
+        const result = await runMessage(event, deps, lambdaContext);
+        console.log(
+            `Report completed: ${result.reportName}, 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: [
+                    {
+                        reportName: event.reportName || 'unknown',
+                        status: 'FAILED',
+                        error: error.message,
+                    },
+                ],
+            }),
+        };
+    }
+}
+
+// SQS batch: each record body is a JSON message. Failures are isolated per
+// record so one bad message doesn't drop the rest of the batch.
+async function handleSqsBatch(event, deps, lambdaContext) {
+    const results = [];
+    for (const record of event.Records) {
+        let message = {};
+        try {
+            message = JSON.parse(record.body);
+            const result = await runMessage(message, deps, lambdaContext);
+            console.log(
+                `Report completed: ${result.reportName}, status: ${result.status}`
+            );
+            results.push(result);
+        } catch (error) {
+            // Report execution errors are handled by ReportRunner; only
+            // unexpected failures (parse, runner construction) reach here.
+            console.error('Unexpected error processing record:', error);
+            await markFailed(message.executionId, error);
+            results.push({
+                reportName: message.reportName || 'unknown',
+                status: 'FAILED',
+                error: error.message,
+            });
+        }
+    }
+
+    return {
+        statusCode: 200,
+        body: JSON.stringify({ processed: results.length, results }),
+    };
+}
+
+/**
+ * Report Executor Lambda handler. Two invocation shapes:
+ * - SQS: `event.Records[]`, each body a JSON execution message.
+ * - EventBridge Scheduler direct invoke: the event itself is the message, no `Records`.
+ */
+async function handler(event, context) {
+    const {
+        reportFactory,
+        reportCommands,
+        reportFriggCommands,
+        integrationFactory,
+    } = bootstrapAdminScripts();
+    const deps = {
+        reportFactory,
+        reportCommands,
+        reportFriggCommands,
+        integrationFactory,
+    };
+
+    return event.Records
+        ? handleSqsBatch(event, deps, context)
+        : handleScheduledInvoke(event, deps, context);
+}
+
+module.exports = { handler };