[APPS][WIP] Initialize Datadog Apps backend runtime

packages/plugins/apps/src/backend/shared.test.ts

@@ -2,7 +2,32 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/).
 // Copyright 2019-Present Datadog, Inc.
 
-import { SET_EXECUTE_ACTION_SNIPPET } from '@dd/apps-plugin/backend/shared';
+import {
+    SET_APPS_BACKEND_RUNTIME_SNIPPET,
+    SET_EXECUTE_ACTION_SNIPPET,
+} from '@dd/apps-plugin/backend/shared';
+
+describe('SET_APPS_BACKEND_RUNTIME_SNIPPET', () => {
+    test('installs a runtime created from the invocation context', () => {
+        const setBackendRuntime = jest.fn();
+        const runtime = { users: { getCurrentUser: jest.fn() } };
+        const createJsFunctionWithActionsRuntime = jest.fn().mockReturnValue(runtime);
+        const context = { Source: { initiator: { id: 'user-id' } } };
+
+        // The snippet references the setup functions and `$` as free variables.
+        // eslint-disable-next-line no-new-func
+        const run = new Function(
+            'setBackendRuntime',
+            'createJsFunctionWithActionsRuntime',
+            '$',
+            SET_APPS_BACKEND_RUNTIME_SNIPPET,
+        );
+        run(setBackendRuntime, createJsFunctionWithActionsRuntime, context);
+
+        expect(createJsFunctionWithActionsRuntime).toHaveBeenCalledWith(context);
+        expect(setBackendRuntime).toHaveBeenCalledWith(runtime);
+    });
+});
 
 /**
  * Evaluate SET_EXECUTE_ACTION_SNIPPET in a controlled scope and return the

packages/plugins/apps/src/backend/shared.ts

@@ -16,10 +16,35 @@ export function isActionCatalogInstalled(fromDir: string): boolean {
     }
 }
 
+/**
+ * Check if the Datadog Apps backend runtime adapter is installed.
+ * Resolve the exported adapter subpath because the package intentionally has
+ * no root export.
+ */
+export function isAppsBackendRuntimeInstalled(fromDir: string): boolean {
+    try {
+        require.resolve('@datadog/apps-backend/runtime/js-function-with-actions', {
+            paths: [fromDir],
+        });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
 /** The import line to pull action-catalog's setExecuteActionImplementation into bundles. */
 export const ACTION_CATALOG_IMPORT =
     "import { setExecuteActionImplementation } from '@datadog/action-catalog/action-execution';";
 
+/** Imports used to install the jsFunctionWithActions backend runtime. */
+export const APPS_BACKEND_RUNTIME_IMPORTS = `\
+import { setBackendRuntime } from '@datadog/apps-backend/runtime';
+import { createJsFunctionWithActionsRuntime } from '@datadog/apps-backend/runtime/js-function-with-actions';`;
+
+/** Install the backend runtime using the invocation context hidden from customer code. */
+export const SET_APPS_BACKEND_RUNTIME_SNIPPET =
+    '    setBackendRuntime(createJsFunctionWithActionsRuntime($));';
+
 /** Script snippet that registers the $.Actions-based executeAction implementation at runtime. */
 export const SET_EXECUTE_ACTION_SNIPPET = `\
     if (typeof setExecuteActionImplementation === 'function') {

packages/plugins/apps/src/backend/virtual-entry.test.ts

@@ -18,6 +18,7 @@ describe('Backend Functions - generateVirtualEntryContent', () => {
     describe('without action-catalog', () => {
         beforeEach(() => {
             jest.spyOn(shared, 'isActionCatalogInstalled').mockReturnValue(false);
+            jest.spyOn(shared, 'isAppsBackendRuntimeInstalled').mockReturnValue(false);
         });
 
         test('Should import the function by name from the entry path', () => {
@@ -89,11 +90,21 @@ describe('Backend Functions - generateVirtualEntryContent', () => {
             );
             expect(result).not.toContain('@datadog/action-catalog');
         });
+
+        test('Should not include apps-backend runtime imports', () => {
+            const result = generateVirtualEntryContent(
+                'myHandler',
+                '/src/handler.ts',
+                PROJECT_ROOT,
+            );
+            expect(result).not.toContain('@datadog/apps-backend');
+        });
     });
 
     describe('with action-catalog', () => {
         beforeEach(() => {
             jest.spyOn(shared, 'isActionCatalogInstalled').mockReturnValue(true);
+            jest.spyOn(shared, 'isAppsBackendRuntimeInstalled').mockReturnValue(false);
         });
 
         test('Should include action-catalog import', () => {
@@ -117,8 +128,44 @@ describe('Backend Functions - generateVirtualEntryContent', () => {
         });
     });
 
+    describe('with apps-backend', () => {
+        beforeEach(() => {
+            jest.spyOn(shared, 'isActionCatalogInstalled').mockReturnValue(false);
+            jest.spyOn(shared, 'isAppsBackendRuntimeInstalled').mockReturnValue(true);
+        });
+
+        test('Should include the runtime imports', () => {
+            const result = generateVirtualEntryContent(
+                'myHandler',
+                '/src/handler.ts',
+                PROJECT_ROOT,
+            );
+
+            expect(result).toContain(
+                "import { setBackendRuntime } from '@datadog/apps-backend/runtime'",
+            );
+            expect(result).toContain(
+                "from '@datadog/apps-backend/runtime/js-function-with-actions'",
+            );
+        });
+
+        test('Should install the runtime before invoking customer code', () => {
+            const result = generateVirtualEntryContent(
+                'myHandler',
+                '/src/handler.ts',
+                PROJECT_ROOT,
+            );
+
+            expect(result).toContain('setBackendRuntime(createJsFunctionWithActionsRuntime($))');
+            expect(result.indexOf('setBackendRuntime(')).toBeLessThan(
+                result.indexOf('await myHandler(...args)'),
+            );
+        });
+    });
+
     test('Should escape entry paths with special characters', () => {
         jest.spyOn(shared, 'isActionCatalogInstalled').mockReturnValue(false);
+        jest.spyOn(shared, 'isAppsBackendRuntimeInstalled').mockReturnValue(false);
         const result = generateVirtualEntryContent(
             'handler',
             '/path/with "quotes"/handler.ts',
@@ -132,6 +179,7 @@ describe('Backend Functions - generateDevVirtualEntryContent', () => {
     beforeEach(() => {
         jest.restoreAllMocks();
         jest.spyOn(shared, 'isActionCatalogInstalled').mockReturnValue(false);
+        jest.spyOn(shared, 'isAppsBackendRuntimeInstalled').mockReturnValue(false);
     });
 
     test('Should produce identical output to generateVirtualEntryContent', () => {
@@ -162,6 +210,7 @@ describe('Backend Functions - args round-trip via $.backendFunctionArgs', () =>
     beforeEach(() => {
         jest.restoreAllMocks();
         jest.spyOn(shared, 'isActionCatalogInstalled').mockReturnValue(false);
+        jest.spyOn(shared, 'isAppsBackendRuntimeInstalled').mockReturnValue(false);
     });
 
     // Extract the body of the generated `main($)` function so we can eval it

packages/plugins/apps/src/backend/virtual-entry.ts

@@ -4,8 +4,11 @@
 
 import {
     ACTION_CATALOG_IMPORT,
+    APPS_BACKEND_RUNTIME_IMPORTS,
+    SET_APPS_BACKEND_RUNTIME_SNIPPET,
     SET_EXECUTE_ACTION_SNIPPET,
     isActionCatalogInstalled,
+    isAppsBackendRuntimeInstalled,
 } from './shared';
 
 /**
@@ -25,11 +28,21 @@ export function generateVirtualEntryContent(
         lines.push(ACTION_CATALOG_IMPORT);
     }
 
+    const hasAppsBackendRuntime = isAppsBackendRuntimeInstalled(projectRoot);
+    if (hasAppsBackendRuntime) {
+        lines.push(APPS_BACKEND_RUNTIME_IMPORTS);
+    }
+
     lines.push('');
     lines.push('/** @param {import("./context.types").Context} $ */');
     lines.push('export async function main($) {');
     lines.push('    globalThis.$ = $;');
     lines.push('');
+    if (hasAppsBackendRuntime) {
+        lines.push('    // Install the backend API implementation for this invocation');
+        lines.push(SET_APPS_BACKEND_RUNTIME_SNIPPET);
+        lines.push('');
+    }
     lines.push(`    // Register the $.Actions-based implementation for executeAction`);
     lines.push(SET_EXECUTE_ACTION_SNIPPET);
     lines.push('');