prototype: local Node execution for backend functions

Adds a Mode-A local execution path for *.backend.ts functions, parallel
to executeScriptViaDatadog (dev-server.ts): a child_process.fork()'d
child runs the real bundled script, with $.Actions calls proxied back
over the fork's built-in IPC channel to the parent.

Not wired into createDevServerMiddleware. executeActionRemotely is a
stub for the single-action execution capability that doesn't exist yet
(see the design doc's Open Dependency section) -- this is an early
prototype for design-doc discussion, not ready to ship.

The $.Actions Proxy get/apply logic in local-exec-child.js is a direct
Node port of the actionplatform Deno script template's makeActionsProxy
(dd-source), which has zero Deno dependencies and copies over verbatim.

local-execution.integration.test.ts is a real, unmocked integration
test: real vite.build(), real getBaseBackendBuildConfig, real
generateDevVirtualEntryContent, against a real *.backend.ts fixture on
disk -- not hand-written stand-ins.

Full design doc: .plans/high-code-apps-local-node-execution-design.md
(dd-source, not yet published to Confluence).

Co-Authored-By: Claude <noreply@anthropic.com>

Author: tyffical

packages/plugins/apps/src/vite/local-exec-child.js

@@ -0,0 +1,100 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the MIT License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2019-Present Datadog, Inc.
+
+/* eslint-env node, es2020 */
+
+// child_process.fork() entry point for local backend-function execution.
+// Plain JS (not TS) deliberately: this is the actual runtime artifact Node
+// forks and executes directly, not source that goes through a build step.
+//
+// The $.Actions Proxy get/apply logic below is a direct Node port of
+// domains/actionplatform/shared/libs/ts/highcode-script-template/render.ts's
+// makeActionsProxy (dd-source) -- that logic has zero Deno dependencies and
+// copies over verbatim. Only the transport changed: Deno.connect + hand-
+// rolled HTTP/1.1 framing over a unix socket is replaced by fork()'s built-in
+// structured-clone IPC channel (process.send()/process.on('message')).
+
+let nextRequestId = 0;
+const pending = new Map();
+
+process.on('message', (msg) => {
+    if (msg && msg.type === 'action-response') {
+        const resolver = pending.get(msg.id);
+        if (resolver) {
+            pending.delete(msg.id);
+            resolver(msg.payload);
+        }
+    }
+});
+
+function callAction(fqn, inputs, connectionId) {
+    return new Promise((resolve, reject) => {
+        const id = ++nextRequestId;
+        pending.set(id, (payload) => {
+            if (payload.type === 'success') {
+                resolve(payload.result);
+            } else {
+                reject(payload.result);
+            }
+        });
+        process.send({ type: 'action-request', id, fqn, inputs, connectionId });
+    });
+}
+
+// Satisfies the exact contract packages/plugins/apps/src/backend/shared.ts's
+// SET_EXECUTE_ACTION_SNIPPET expects: $.Actions must resolve any nested
+// property path (e.g. $.Actions.slack.chat.postMessage) to a callable.
+function makeActionsProxy(pathParts = []) {
+    return new Proxy(function () {}, {
+        get(_target, prop) {
+            return makeActionsProxy(pathParts.concat(String(prop)));
+        },
+        apply(_target, _thisArg, args) {
+            if (args.length === 0) {
+                return Promise.reject(
+                    `No arguments provided to action $.Actions.${pathParts.join('.')}`,
+                );
+            }
+            const { inputs, connectionId } = args[0];
+            if (typeof inputs !== 'object' || !inputs) {
+                return Promise.reject(
+                    `First argument to action $.Actions.${pathParts.join('.')} must have an inputs field`,
+                );
+            }
+            const fqn = `com.datadoghq.${pathParts.join('.')}`;
+            return callAction(fqn, inputs, connectionId);
+        },
+    });
+}
+
+process.on('message', async function onExecute(msg) {
+    if (!msg || msg.type !== 'execute') {
+        return;
+    }
+
+    try {
+        const $ = { backendFunctionArgs: msg.backendFunctionArgs, Actions: makeActionsProxy() };
+        globalThis.$ = $;
+
+        // The real bundled code (from vite.build(), format:'es', no externals
+        // for real npm deps -- see build-config.ts) is a plain ES module string
+        // exporting `main`. Importing it as a data: URL avoids writing a temp
+        // file. Verified empirically: this only works because Rollup inlines
+        // every resolvable npm dependency (no `external` array configured) --
+        // genuine Node built-ins (crypto, fs, etc.) are the only bare imports
+        // left in real output, and those resolve fine from a data: URL since
+        // they're resolved by scheme, not by filesystem context. A bare
+        // specifier for an actual unresolved npm package would fail here with
+        // "Failed to resolve module specifier" -- confirmed by direct test.
+        const dataUrl = `data:text/javascript;base64,${Buffer.from(msg.scriptBody).toString('base64')}`;
+        const mod = await import(dataUrl);
+        const result = await mod.main($);
+
+        process.send({ type: 'result', result });
+        process.exit(0);
+    } catch (err) {
+        process.send({ type: 'error', error: String(err && err.message ? err.message : err) });
+        process.exit(1);
+    }
+});

packages/plugins/apps/src/vite/local-execution.integration.test.ts

@@ -0,0 +1,138 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the MIT License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2019-Present Datadog, Inc.
+
+/**
+ * Real, unmocked integration test for the local-execution implementation
+ * POC (.plans/high-code-apps-local-node-execution-design.md in dd-source).
+ *
+ * Unlike dev-server.test.ts (which mocks vite.build entirely), this test
+ * uses the REAL vite.build(), REAL getBaseBackendBuildConfig, and REAL
+ * generateDevVirtualEntryContent -- the exact same bundling path
+ * bundleBackendFunction() in dev-server.ts uses -- then feeds that real
+ * bundled output through executeScriptLocally(), proving the new local
+ * execution path works against a genuine bundle, not a hand-written stand-in.
+ */
+
+import { outputFileSync } from '@dd/core/helpers/fs';
+import { getTempWorkingDir } from '@dd/tests/_jest/helpers/env';
+import { getMockLogger } from '@dd/tests/_jest/helpers/mocks';
+import { build } from 'vite';
+
+import type { BackendFunction } from '../backend/types';
+import { generateDevVirtualEntryContent } from '../backend/virtual-entry';
+
+import { getBaseBackendBuildConfig } from './build-config';
+import { executeScriptLocally } from './local-execution';
+
+const log = getMockLogger();
+
+async function bundleRealBackendFunction(
+    workingDir: string,
+    functionName: string,
+    sourceCode: string,
+): Promise<string> {
+    const absolutePath = `${workingDir}/src/${functionName}.backend.ts`;
+    outputFileSync(absolutePath, sourceCode);
+
+    const virtualId = `virtual:dd-backend-dev:${functionName}`;
+    const virtualContent = generateDevVirtualEntryContent(functionName, absolutePath, workingDir);
+    const baseConfig = getBaseBackendBuildConfig(workingDir, { [virtualId]: virtualContent }, []);
+
+    const result = await build({
+        ...baseConfig,
+        build: {
+            ...baseConfig.build,
+            write: false,
+            rollupOptions: {
+                ...baseConfig.build.rollupOptions,
+                input: virtualId,
+                output: baseConfig.build.rollupOptions.output,
+            },
+        },
+    });
+
+    const output = Array.isArray(result) ? result[0] : result;
+    if (!('output' in output)) {
+        throw new Error('Unexpected vite.build result');
+    }
+    const chunk = output.output[0];
+    return chunk.type === 'chunk' ? chunk.code : '';
+}
+
+describe('executeScriptLocally (real bundle, no mocks)', () => {
+    test('runs a real Rollup-bundled *.backend.ts function locally and calls $.Actions through the local child', async () => {
+        const workingDir = getTempWorkingDir(`local-exec-poc-${Date.now()}`);
+
+        // A real sample backend function -- calls $.Actions like a customer's
+        // real *.backend.ts file would, plus a genuine Node built-in import
+        // (crypto) to exercise the data:-URL-import concern documented in
+        // local-exec-child.js.
+        const sourceCode = `
+            import { randomBytes } from 'node:crypto';
+            export async function greet(name) {
+                const nonce = randomBytes(4).toString('hex');
+                const response = await $.Actions.slack.chat.postMessage({
+                    inputs: { channel: '#test', text: 'hello ' + name },
+                    connectionId: 'connection:slack:poc',
+                });
+                return { greeting: 'hello ' + name, nonce, actionResult: response };
+            }
+        `;
+
+        const code = await bundleRealBackendFunction(workingDir, 'greet', sourceCode);
+
+        // Sanity check on the real bundle output itself, before executing it:
+        // confirms Rollup actually inlined everything real-npm and left only
+        // the genuine Node built-in as a bare import (the assumption
+        // local-exec-child.js's data:-URL-import approach depends on).
+        expect(code).toContain("from 'node:crypto'");
+        expect(code).not.toContain('@datadog/action-catalog'); // not installed in this fixture -> no snippet at all
+        // Rollup's preserveEntrySignatures:'exports-only' rewrites the inline
+        // `export async function main($)` into a plain declaration plus a
+        // separate `export { main };` -- assert on real Rollup output shape,
+        // not the pre-bundling source template's shape.
+        expect(code).toMatch(/async function main\(\$\)/);
+        expect(code).toContain('export { main }');
+
+        const func: BackendFunction = {
+            relativePath: 'src/greet',
+            name: 'greet',
+            absolutePath: `${workingDir}/src/greet.backend.ts`,
+            allowedConnectionIds: ['connection:slack:poc'],
+        };
+
+        const outputs = await executeScriptLocally(code, func, ['world'], log);
+
+        // $.Actions.foo.bar(...) resolves to the raw result value directly
+        // (already unwrapped from the internal {type, result} envelope) --
+        // matches the real contract in shared.ts's SET_EXECUTE_ACTION_SNIPPET
+        // (`return actionFn(request)`, not `return {type, result}`).
+        expect(outputs.data).toMatchObject({
+            greeting: 'hello world',
+            actionResult: { data: null, stub: true, fqn: 'com.datadoghq.slack.chat.postMessage' },
+        });
+        expect((outputs.data as { nonce: string }).nonce).toMatch(/^[0-9a-f]{8}$/);
+    }, 20_000);
+
+    test('propagates a real crash (uncaught throw in the bundled function) as a rejected promise, not a hang', async () => {
+        const workingDir = getTempWorkingDir(`local-exec-poc-crash-${Date.now()}`);
+        const sourceCode = `
+            export async function crashes() {
+                throw new Error('deliberate bug in a real bundled backend function');
+            }
+        `;
+        const code = await bundleRealBackendFunction(workingDir, 'crashes', sourceCode);
+
+        const func: BackendFunction = {
+            relativePath: 'src/crashes',
+            name: 'crashes',
+            absolutePath: `${workingDir}/src/crashes.backend.ts`,
+            allowedConnectionIds: [],
+        };
+
+        await expect(executeScriptLocally(code, func, [], log)).rejects.toThrow(
+            'deliberate bug in a real bundled backend function',
+        );
+    }, 20_000);
+});

packages/plugins/apps/src/vite/local-execution.ts

@@ -0,0 +1,144 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the MIT License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/).
+// Copyright 2019-Present Datadog, Inc.
+
+/**
+ * Local Node execution for backend functions -- the "Mode A" path described
+ * in the design doc (.plans/high-code-apps-local-node-execution-design.md
+ * in dd-source). This is an implementation POC, not production code: it is
+ * NOT wired into createDevServerMiddleware, and executeActionRemotely below
+ * is a stub for the single-action execution endpoint that doesn't exist yet
+ * (see the design doc's "Open Dependency" section).
+ *
+ * Parallel structure to executeScriptViaDatadog in dev-server.ts: same
+ * BackendOutputs return shape, so it's a drop-in alternate implementation
+ * behind the same contract, not a protocol change.
+ */
+
+import type { Logger } from '@dd/core/types';
+import { fork } from 'child_process';
+import * as path from 'path';
+
+import type { BackendFunction } from '../backend/types';
+
+type BackendOutputs = { data: unknown };
+
+interface ActionRequestMessage {
+    type: 'action-request';
+    id: number;
+    fqn: string;
+    inputs: Record<string, unknown>;
+    connectionId?: string;
+}
+
+type ChildMessage =
+    | ActionRequestMessage
+    | { type: 'result'; result: unknown }
+    | { type: 'error'; error: string };
+
+const LOCAL_EXEC_CHILD_SCRIPT = path.join(__dirname, 'local-exec-child.js');
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * TODO(open-dependency): stub for the single-action execution capability the
+ * design doc asks the Action Platform team to build (a new REST endpoint or
+ * an MCP tool -- see "Open Dependency"). This is the ONLY function that
+ * reaches outward for a real $.Actions call; once the real endpoint exists,
+ * only this function's body needs to change.
+ */
+async function executeActionRemotely(
+    request: ActionRequestMessage,
+    log: Logger,
+): Promise<{ type: 'success' | 'failure'; result: unknown }> {
+    log.debug(
+        `[local-execution] (stub -- no real endpoint exists yet) would call ${request.fqn} with inputs=${JSON.stringify(request.inputs)}`,
+    );
+    return { type: 'success', result: { data: null, stub: true, fqn: request.fqn } };
+}
+
+/**
+ * Execute a bundled backend function locally via a forked Node child process,
+ * with $.Actions calls proxied back through this function (which currently
+ * stubs the outward call -- see executeActionRemotely above).
+ */
+export function executeScriptLocally(
+    scriptBody: string,
+    func: BackendFunction,
+    args: unknown[],
+    log: Logger,
+    timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): Promise<BackendOutputs> {
+    return new Promise((resolve, reject) => {
+        // NOTE: production implementation must pass an explicit restricted
+        // `env`, never inherit process.env wholesale -- see the design doc's
+        // Secrets Handling section (never hand secrets to the child).
+        const child = fork(LOCAL_EXEC_CHILD_SCRIPT, [], { stdio: 'inherit', env: {} });
+        let settled = false;
+
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                child.kill();
+                reject(
+                    new Error(`Local execution of "${func.name}" timed out after ${timeoutMs}ms`),
+                );
+            }
+        }, timeoutMs);
+
+        child.on('message', (msg: ChildMessage) => {
+            if (!msg) {
+                return;
+            }
+
+            if (msg.type === 'action-request') {
+                executeActionRemotely(msg, log)
+                    .then((response) => {
+                        child.send({ type: 'action-response', id: msg.id, payload: response });
+                    })
+                    .catch((err: unknown) => {
+                        child.send({
+                            type: 'action-response',
+                            id: msg.id,
+                            payload: { type: 'failure', result: String(err) },
+                        });
+                    });
+                return;
+            }
+
+            if (msg.type === 'result' && !settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve({ data: msg.result });
+                return;
+            }
+
+            if (msg.type === 'error' && !settled) {
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error(msg.error));
+            }
+        });
+
+        child.on('exit', (code) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                reject(
+                    new Error(
+                        `Local execution of "${func.name}" exited with code ${code} before reporting a result`,
+                    ),
+                );
+            }
+        });
+
+        child.on('error', (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                reject(err);
+            }
+        });
+
+        child.send({ type: 'execute', scriptBody, backendFunctionArgs: args });
+    });
+}