refactor(base-runtime): extract shared base-runtime from node/deno trees

Move the 52 shared runtime files (handlers, accessors, lib, AST,
AppObjectRegistry, and their tests) into a single base-runtime/ tree,
deleting the duplicated copies that lived in both node-runtime/src and
deno-runtime. The base is now the single source for everything that is
not a platform seam.

Three base-only changes make the tree self-contained:
- construct.ts becomes single-source: sandbox require and the eval-shell
  globals are injected via setSandboxRequire/setSandboxGlobals (defaults
  no-op), the App import is type-only, and the platform Socket patch is
  removed (hoisted to the Deno adapter bootstrap).
- the message loop is extracted to messageLoop.ts (startMessageLoop),
  leaving transport/error-listener wiring to each adapter.
- the anonymous Queue class in messenger.ts is named so the base can
emit
  declarations; the base messenger test no longer references a platform
  transport.

base-runtime/tsconfig.json compiles the tree with the runtime-flavored
settings (nodenext, es2023, types: node) to base-runtime/dist.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

refactor(base-runtime): messageLoop to mainLoop

refactor(base-runtime): better directory structure

install base-runtime dependencies in the apps package

fix(base-runtime): import fixes

refactor(base-runtime): move the full require logic out of construct.ts

Module resolution is the responsibility of the platform

Author: d-gubert

packages/apps/base-runtime/src/AppObjectRegistry.ts

@@ -0,0 +1,25 @@
+export type Maybe<T> = T | null | undefined;
+
+export const AppObjectRegistry = new (class {
+	registry: Record<string, unknown> = {};
+
+	public get<T>(key: string): Maybe<T> {
+		return this.registry[key] as Maybe<T>;
+	}
+
+	public set(key: string, value: unknown): void {
+		this.registry[key] = value;
+	}
+
+	public has(key: string): boolean {
+		return key in this.registry;
+	}
+
+	public delete(key: string): void {
+		delete this.registry[key];
+	}
+
+	public clear(): void {
+		this.registry = {};
+	}
+})();

packages/apps/base-runtime/src/handlers/api-handler.ts

@@ -0,0 +1,51 @@
+import type { IApiEndpoint } from '@rocket.chat/apps-engine/definition/api/IApiEndpoint';
+import type { Defined } from 'jsonrpc-lite';
+import { JsonRpcError } from 'jsonrpc-lite';
+
+import { AppObjectRegistry } from '../AppObjectRegistry';
+import { AppAccessorsInstance } from '../lib/accessors/mod';
+import type { RequestContext } from '../lib/requestContext';
+import { wrapComposedApp } from '../lib/wrapAppForRequest';
+
+export default async function apiHandler(request: RequestContext): Promise<JsonRpcError | Defined> {
+	const { method: call, params } = request;
+	const [, /* always "api" */ ...parts] = call.split(':');
+	const httpMethod = parts.pop();
+	const path = parts.join(':');
+
+	const endpoint = AppObjectRegistry.get<IApiEndpoint>(`api:${path}`);
+	const { logger } = request.context;
+
+	if (!endpoint) {
+		return new JsonRpcError(`Endpoint ${path} not found`, -32000);
+	}
+
+	const method = endpoint[httpMethod as keyof IApiEndpoint];
+
+	if (typeof method !== 'function') {
+		return new JsonRpcError(`${path}'s ${httpMethod} not exists`, -32000);
+	}
+
+	const [requestData, endpointInfo] = params as Array<unknown>;
+
+	logger.debug(`${path}'s ${call} is being executed...`, requestData);
+
+	try {
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+		const result = await (method as Function).apply(wrapComposedApp(endpoint, request), [
+			requestData,
+			endpointInfo,
+			AppAccessorsInstance.getReader(),
+			AppAccessorsInstance.getModifier(),
+			AppAccessorsInstance.getHttp(),
+			AppAccessorsInstance.getPersistence(),
+		]);
+
+		logger.debug(`${path}'s ${call} was successfully executed.`);
+
+		return result;
+	} catch (e) {
+		logger.debug(`${path}'s ${call} was unsuccessful.`);
+		return new JsonRpcError(e.message || 'Internal server error', -32000);
+	}
+}

packages/apps/base-runtime/src/handlers/app/construct.ts

@@ -0,0 +1,130 @@
+import type { IParseAppPackageResult } from '@rocket.chat/apps/dist/server/compiler/IParseAppPackageResult';
+import type { App } from '@rocket.chat/apps-engine/definition/App';
+
+import { AppObjectRegistry } from '../../AppObjectRegistry';
+import { AppAccessorsInstance } from '../../lib/accessors/mod';
+import type { RequestContext } from '../../lib/requestContext';
+import { sanitizeDeprecatedUsage } from '../../lib/sanitizeDeprecatedUsage';
+
+/**
+ * A platform-dependent `require` used to resolve the modules an app is allowed
+ * to load (native `node:` modules, a small allow-list of npm packages, and
+ * apps-engine files). Each runtime injects its own via {@link setSandboxRequire}
+ * — Node hands over its global `require`, Deno hands over its `createRequire`
+ * shim that knows how to resolve compiled apps-engine paths.
+ */
+type SandboxRequire = (module: string) => unknown;
+
+function defaultSandboxRequire(): never {
+	throw new Error('No sandbox require has been injected; the runtime adapter must call setSandboxRequire() during bootstrap');
+}
+
+let sandboxRequire: SandboxRequire = defaultSandboxRequire;
+
+export function setSandboxRequire(newRequire: SandboxRequire): void {
+	sandboxRequire = newRequire;
+}
+
+/**
+ * Extra globals bound into the app's eval shell on top of the common ones
+ * (`exports`, `module`, `require`, `console`, `globalThis`). Node needs none;
+ * Deno injects a `Buffer` and shadows `Deno` with `undefined`. Injecting them
+ * as data keeps the eval-shell skeleton single-source.
+ */
+type SandboxGlobals = Record<string, unknown>;
+
+let sandboxGlobals: SandboxGlobals = {};
+
+export function setSandboxGlobals(globals: SandboxGlobals): void {
+	sandboxGlobals = globals;
+}
+
+function wrapAppCode(code: string): (require: SandboxRequire) => Promise<Record<string, unknown>> {
+	const globals = sandboxGlobals;
+	// The common globals are bound by name; any platform-specific extras are
+	// spread in by name from the injected `sandboxGlobals`, so the shell
+	// skeleton stays identical across runtimes.
+	const extraNames = Object.keys(globals);
+	const extraParams = extraNames.length ? `,${extraNames.join(',')}` : '';
+	const extraArgs = extraNames.map((name) => `,__globals[${JSON.stringify(name)}]`).join('');
+
+	// eslint-disable-next-line @typescript-eslint/no-implied-eval -- This is the reason we run in a separate process
+	const fn = new Function(
+		'require',
+		'__globals',
+		`
+        const exports = {};
+        const module = { exports };
+        const _error = console.error.bind(console);
+        const _console = {
+            log: _error,
+            error: _error,
+            debug: _error,
+            info: _error,
+            warn: _error,
+        };
+
+        const result = (async (exports,module,require,console,globalThis${extraParams}) => {
+            ${code};
+        })(exports,module,require,_console,undefined${extraArgs});
+
+        return result.then(() => module.exports);`,
+	) as (require: SandboxRequire, globals: SandboxGlobals) => Promise<Record<string, unknown>>;
+
+	return (require: SandboxRequire) => fn(require, globals);
+}
+
+type AppConstructor = new (...args: unknown[]) => App;
+
+export default async function handleConstructApp(request: RequestContext): Promise<boolean> {
+	const { params } = request;
+
+	if (!Array.isArray(params)) {
+		throw new Error('Invalid params', { cause: 'invalid_param_type' });
+	}
+
+	const [appPackage] = params as [IParseAppPackageResult];
+
+	if (!appPackage?.info?.id || !appPackage?.info?.classFile || !appPackage?.files) {
+		throw new Error('Invalid params', { cause: 'invalid_param_type' });
+	}
+
+	AppObjectRegistry.set('id', appPackage.info.id);
+	const source = sanitizeDeprecatedUsage(appPackage.files[appPackage.info.classFile]);
+
+	const exports = await wrapAppCode(source)(sandboxRequire);
+
+	// This is the same naive logic we've been using in the App Compiler
+	// Applying the correct type here is quite difficult because of the dynamic nature of the code
+	const appClass = Object.values(exports)[0] as AppConstructor;
+
+	const app = new appClass(appPackage.info, request.context.logger, AppAccessorsInstance.getDefaultAppAccessors());
+
+	if (typeof app.getName !== 'function') {
+		throw new Error('App must contain a getName function');
+	}
+
+	if (typeof app.getNameSlug !== 'function') {
+		throw new Error('App must contain a getNameSlug function');
+	}
+
+	if (typeof app.getVersion !== 'function') {
+		throw new Error('App must contain a getVersion function');
+	}
+
+	if (typeof app.getID !== 'function') {
+		throw new Error('App must contain a getID function');
+	}
+
+	if (typeof app.getDescription !== 'function') {
+		throw new Error('App must contain a getDescription function');
+	}
+
+	if (typeof app.getRequiredApiVersion !== 'function') {
+		throw new Error('App must contain a getRequiredApiVersion function');
+	}
+
+	AppObjectRegistry.set('app', app);
+
+	return true;
+}

packages/apps/base-runtime/src/handlers/app/handleGetStatus.ts

@@ -0,0 +1,16 @@
+import type { App } from '@rocket.chat/apps-engine/definition/App';
+import type { AppStatus } from '@rocket.chat/apps-engine/definition/AppStatus';
+
+import { AppObjectRegistry } from '../../AppObjectRegistry';
+
+export default function handleGetStatus(): Promise<AppStatus> {
+	const app = AppObjectRegistry.get<App>('app');
+
+	if (typeof app?.getStatus !== 'function') {
+		throw new Error('App must contain a getStatus function', {
+			cause: 'invalid_app',
+		});
+	}
+
+	return app.getStatus();
+}

packages/apps/base-runtime/src/handlers/app/handleInitialize.ts

@@ -0,0 +1,24 @@
+import type { App } from '@rocket.chat/apps-engine/definition/App';
+
+import { AppObjectRegistry } from '../../AppObjectRegistry';
+import { AppAccessorsInstance } from '../../lib/accessors/mod';
+import type { RequestContext } from '../../lib/requestContext';
+import { wrapAppForRequest } from '../../lib/wrapAppForRequest';
+
+export default async function handleInitialize(request: RequestContext): Promise<boolean> {
+	const app = AppObjectRegistry.get<App>('app');
+
+	if (typeof app?.initialize !== 'function') {
+		throw new Error('App must contain an initialize function', {
+			cause: 'invalid_app',
+		});
+	}
+
+	await app.initialize.call(
+		wrapAppForRequest(app, request),
+		AppAccessorsInstance.getConfigurationExtend(),
+		AppAccessorsInstance.getEnvironmentRead(),
+	);
+
+	return true;
+}

packages/apps/base-runtime/src/handlers/app/handleOnDisable.ts

@@ -0,0 +1,20 @@
+import type { App } from '@rocket.chat/apps-engine/definition/App';
+
+import { AppObjectRegistry } from '../../AppObjectRegistry';
+import { AppAccessorsInstance } from '../../lib/accessors/mod';
+import type { RequestContext } from '../../lib/requestContext';
+import { wrapAppForRequest } from '../../lib/wrapAppForRequest';
+
+export default async function handleOnDisable(request: RequestContext): Promise<boolean> {
+	const app = AppObjectRegistry.get<App>('app');
+
+	if (typeof app?.onDisable !== 'function') {
+		throw new Error('App must contain an onDisable function', {
+			cause: 'invalid_app',
+		});
+	}
+
+	await app.onDisable.call(wrapAppForRequest(app, request), AppAccessorsInstance.getConfigurationModify());
+
+	return true;
+}

packages/apps/base-runtime/src/handlers/app/handleOnEnable.ts

@@ -0,0 +1,22 @@
+import type { App } from '@rocket.chat/apps-engine/definition/App';
+
+import { AppObjectRegistry } from '../../AppObjectRegistry';
+import { AppAccessorsInstance } from '../../lib/accessors/mod';
+import type { RequestContext } from '../../lib/requestContext';
+import { wrapAppForRequest } from '../../lib/wrapAppForRequest';
+
+export default function handleOnEnable(request: RequestContext): Promise<boolean> {
+	const app = AppObjectRegistry.get<App>('app');
+
+	if (typeof app?.onEnable !== 'function') {
+		throw new Error('App must contain an onEnable function', {
+			cause: 'invalid_app',
+		});
+	}
+
+	return app.onEnable.call(
+		wrapAppForRequest(app, request),
+		AppAccessorsInstance.getEnvironmentRead(),
+		AppAccessorsInstance.getConfigurationModify(),
+	);
+}

packages/apps/base-runtime/src/handlers/app/handleOnInstall.ts

@@ -0,0 +1,34 @@
+import type { App } from '@rocket.chat/apps-engine/definition/App';
+
+import { AppObjectRegistry } from '../../AppObjectRegistry';
+import { AppAccessorsInstance } from '../../lib/accessors/mod';
+import type { RequestContext } from '../../lib/requestContext';
+import { wrapAppForRequest } from '../../lib/wrapAppForRequest';
+
+export default async function handleOnInstall(request: RequestContext): Promise<boolean> {
+	const { params } = request;
+	const app = AppObjectRegistry.get<App>('app');
+
+	if (typeof app?.onInstall !== 'function') {
+		throw new Error('App must contain an onInstall function', {
+			cause: 'invalid_app',
+		});
+	}
+
+	if (!Array.isArray(params)) {
+		throw new Error('Invalid params', { cause: 'invalid_param_type' });
+	}
+
+	const [context] = params as [Record<string, unknown>];
+
+	await app.onInstall.call(
+		wrapAppForRequest(app, request),
+		context,
+		AppAccessorsInstance.getReader(),
+		AppAccessorsInstance.getHttp(),
+		AppAccessorsInstance.getPersistence(),
+		AppAccessorsInstance.getModifier(),
+	);
+
+	return true;
+}

packages/apps/base-runtime/src/handlers/app/handleOnPreSettingUpdate.ts

@@ -0,0 +1,31 @@
+import type { App } from '@rocket.chat/apps-engine/definition/App';
+
+import { AppObjectRegistry } from '../../AppObjectRegistry';
+import { AppAccessorsInstance } from '../../lib/accessors/mod';
+import type { RequestContext } from '../../lib/requestContext';
+import { wrapAppForRequest } from '../../lib/wrapAppForRequest';
+
+export default function handleOnPreSettingUpdate(request: RequestContext): Promise<object> {
+	const { params } = request;
+	const app = AppObjectRegistry.get<App>('app');
+
+	if (typeof app?.onPreSettingUpdate !== 'function') {
+		throw new Error('App must contain an onPreSettingUpdate function', {
+			cause: 'invalid_app',
+		});
+	}
+
+	if (!Array.isArray(params)) {
+		throw new Error('Invalid params', { cause: 'invalid_param_type' });
+	}
+
+	const [setting] = params as [Record<string, unknown>];
+
+	return app.onPreSettingUpdate.call(
+		wrapAppForRequest(app, request),
+		setting,
+		AppAccessorsInstance.getConfigurationModify(),
+		AppAccessorsInstance.getReader(),
+		AppAccessorsInstance.getHttp(),
+	);
+}

packages/apps/base-runtime/src/handlers/app/handleOnSettingUpdated.ts

@@ -0,0 +1,33 @@
+import type { App } from '@rocket.chat/apps-engine/definition/App';
+
+import { AppObjectRegistry } from '../../AppObjectRegistry';
+import { AppAccessorsInstance } from '../../lib/accessors/mod';
+import type { RequestContext } from '../../lib/requestContext';
+import { wrapAppForRequest } from '../../lib/wrapAppForRequest';
+
+export default async function handleOnSettingUpdated(request: RequestContext): Promise<boolean> {
+	const { params } = request;
+	const app = AppObjectRegistry.get<App>('app');
+
+	if (typeof app?.onSettingUpdated !== 'function') {
+		throw new Error('App must contain an onSettingUpdated function', {
+			cause: 'invalid_app',
+		});
+	}
+
+	if (!Array.isArray(params)) {
+		throw new Error('Invalid params', { cause: 'invalid_param_type' });
+	}
+
+	const [setting] = params as [Record<string, unknown>];
+
+	await app.onSettingUpdated.call(
+		wrapAppForRequest(app, request),
+		setting,
+		AppAccessorsInstance.getConfigurationModify(),
+		AppAccessorsInstance.getReader(),
+		AppAccessorsInstance.getHttp(),
+	);
+
+	return true;
+}