feat(apps): introduce node-runtime

refactor(apps): reduce node-runtime to a thin base adapter

node-runtime now keeps only its platform seam: main.ts is a bootstrap
that wires the stdout transport, the sandbox require (Node's global
require) and empty sandbox globals, registers error listeners, then
invokes the base message loop. error-handlers and stdoutTransport import
the base messenger via the compiled specifier
@rocket.chat/apps/base-runtime/dist/..., resolved by the existing
loader-hook. Drop the stray debug console.error from loader-hook now
that
real runtime imports flow through it.

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

node-runtime main.ts comment

Author: d-gubert

packages/apps/deno-runtime/main.ts

@@ -17,7 +17,7 @@ import { stdoutTransport } from './lib/transports/stdoutTransport';
 
 if (!process.argv.includes('--subprocess')) {
 	console.error(`
-            This is a Deno wrapper for Rocket.Chat Apps. It is not meant to be executed stand-alone;
+            This is the Deno wrapper for the Rocket.Chat Apps runtime. It is not meant to be executed stand-alone;
             It is instead meant to be executed as a subprocess by the Apps-Engine framework.
 	`);
 

packages/apps/node-runtime/src/error-handlers.ts

@@ -0,0 +1,10 @@
+import * as Messenger from '@rocket.chat/apps/base-runtime/dist/lib/messenger';
+
+export default function registerErrorListeners() {
+	process.on('uncaughtException', (error: Error, origin: 'uncaughtException' | 'unhandledRejection') => {
+		Messenger.sendNotification({
+			method: origin,
+			params: [error.stack || error],
+		});
+	});
+}

packages/apps/node-runtime/src/lib/loader-hook.ts

@@ -0,0 +1,19 @@
+import { registerHooks } from 'node:module';
+import path from 'node:path';
+
+// This file compiles to dist/lib/loader-hook.js.
+// Three levels up from dist/lib/ lands on packages/apps/ — the @rocket.chat/apps package root.
+const appsPackageDir = path.resolve(__dirname, '../../..');
+
+const PACKAGE_PREFIX = '@rocket.chat/apps';
+
+registerHooks({
+	resolve(specifier, context, nextResolve) {
+		if (specifier === PACKAGE_PREFIX || specifier.startsWith(`${PACKAGE_PREFIX}/`)) {
+			const subpath = specifier.slice(PACKAGE_PREFIX.length).replace(/^\//, '');
+			const localPath = subpath ? path.join(appsPackageDir, subpath) : appsPackageDir;
+			return nextResolve(localPath, context);
+		}
+		return nextResolve(specifier, context);
+	},
+});

packages/apps/node-runtime/src/lib/require.ts

@@ -0,0 +1,36 @@
+const ALLOWED_MODULES = [
+	'path',
+	'url',
+	'crypto',
+	'buffer',
+	'stream',
+	'net',
+	'http',
+	'https',
+	'zlib',
+	'util',
+	'punycode',
+	'os',
+	'querystring',
+	'fs',
+	// External libraries
+	'uuid',
+	'@rocket.chat/apps-engine',
+];
+
+// As the apps are bundled, the only times they will call require are
+// 1. To require native modules
+// 2. To require external npm packages we may provide
+// 3. To require apps-engine files
+export const sandboxRequire = (module: string) => {
+	// Normalize Node built-in specifiers: accept both 'crypto' and 'node:crypto'
+	const normalized = module.replace('node:', '');
+
+	if (!ALLOWED_MODULES.includes(normalized)) {
+		throw new Error(`Module ${module} is not allowed`);
+	}
+
+	// This is THE purpose of this function, we can't escape a dinamyc require call
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-return, import/no-dynamic-require, @typescript-eslint/no-require-imports
+	return require(normalized);
+};

packages/apps/node-runtime/src/lib/transports/stdoutTransport.ts

@@ -0,0 +1,16 @@
+import type { Transport } from '@rocket.chat/apps/base-runtime/dist/lib/messenger';
+
+/**
+ * Transport that writes messages to the process' standard output.
+ *
+ * This is the transport used when the runtime is executed as a subprocess by
+ * the Apps-Engine framework, and it is specific to platforms that expose a
+ * Node-compatible `process.stdout`.
+ */
+export const stdoutTransport: Transport = {
+	async send(message: Uint8Array): Promise<void> {
+		await new Promise<void>((resolve, reject) => {
+			process.stdout.write(message, (err) => (err ? reject(err) : resolve()));
+		});
+	},
+};

packages/apps/node-runtime/src/main.ts

@@ -0,0 +1,32 @@
+import './lib/loader-hook';
+
+import { setSandboxGlobals, setSandboxRequire } from '@rocket.chat/apps/base-runtime/dist/handlers/app/construct';
+import { setTransport } from '@rocket.chat/apps/base-runtime/dist/lib/messenger';
+import { startMainLoop } from '@rocket.chat/apps/base-runtime/dist/mainLoop';
+
+import registerErrorListeners from './error-handlers';
+import { sandboxRequire } from './lib/require';
+import { stdoutTransport } from './lib/transports/stdoutTransport';
+
+if (!process.argv.includes('--subprocess')) {
+	console.error(
+		new TextEncoder().encode(`
+            This is the Node wrapper for the Rocket.Chat Apps runtime. It is not meant to be executed stand-alone;
+            It is instead meant to be executed as a subprocess by the Apps-Engine framework.
+       `),
+	);
+
+	process.exit(1);
+}
+
+// This runtime communicates with the Apps-Engine host through stdout
+setTransport(stdoutTransport);
+
+// The sandbox `require` handed to the app is Node's own global `require`; it
+// needs no extra globals beyond the common ones the base eval shell binds.
+setSandboxRequire(sandboxRequire);
+setSandboxGlobals({});
+
+registerErrorListeners();
+
+void startMainLoop();

packages/apps/node-runtime/tsconfig.json

@@ -0,0 +1,18 @@
+{
+	"extends": "../tsconfig.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist",
+		"baseUrl": ".",
+		"types": ["node"],
+		"lib": ["es2023"],
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
+		"target": "es2023",
+		"declaration": true,
+		"paths": {
+			"@rocket.chat/apps/*": ["../*"]
+		}
+	},
+	"include": ["./src/**/*"]
+}

packages/apps/package.json

@@ -7,14 +7,16 @@
 	"files": [
 		"dist/",
 		"base-runtime/",
+		"node-runtime/",
 		"deno-runtime/",
 		".deno-cache/"
 	],
 	"scripts": {
-		"build": "run-s build:clean build:default build:base-runtime build:deno-cache",
+		"build": "run-s build:clean build:default build:base-runtime build:node-runtime build:deno-cache",
 		"build:clean": "rimraf dist base-runtime/dist",
 		"build:default": "tsc -p tsconfig.json",
 		"build:base-runtime": "tsc -p base-runtime/tsconfig.json",
+		"build:node-runtime": "tsc -p node-runtime/tsconfig.json",
 		"build:deno-cache": "node scripts/deno-cache.js",
 		"dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
 		"lint": "eslint .",

packages/apps/turbo.json

@@ -4,7 +4,7 @@
         "build": {
             "dependsOn": ["^build"],
             "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/.tool-versions"],
-            "outputs": ["base-runtime/**", "deno-runtime/**", "scripts/**", ".deno-cache/**", "dist/**"]
+            "outputs": ["base-runtime/**", "node-runtime/**", "deno-runtime/**", "scripts/**", ".deno-cache/**", "dist/**"]
         }
     }
 }