Plan: Node runtime to replace Deno runtime for apps-engine subprocess

[Copilot]

Comprehensive analysis of deno-runtime/ and migration plan to a node-runtime that preserves identical behavior without Deno-specific APIs.

Deno API inventory

Cataloged all Deno-specific surface area across ~25 files:

• Direct globals: Deno.stdin.readable, Deno.stdout, Deno.stderr, Deno.args, Deno.pid, Deno.exit(), Deno.open()
• Std library: @std/io (writeAll), @std/cli (parseArgs), @std/streams (toArrayBuffer)
• Missing in Node: ErrorEvent (needs polyfill), global addEventListener('unhandledrejection') → process.on('unhandledRejection')
• Import maps: deno.jsonc import maps power @rocket.chat/apps-engine/ resolution and import.meta.resolve() — no Node equivalent

~10 of ~25 files need changes; the rest are already Node-compatible.

Node permission model mapping

Deno	Node (--permission)	Gap?
--allow-read=<dirs>	--allow-fs-read=<dirs>	No
--allow-env=VAR1,VAR2	N/A (strip env at spawn)	Already mitigated — spawnProcess() only passes PATH
--allow-net	No equivalent	Yes — apps use accessor proxy for HTTP, practical impact limited

TypeScript support

Node 22.7+ --experimental-transform-types handles all syntax in the codebase. The single enum in lib/logger.ts requires transform (not just strip). .ts import extensions work natively.

AppRuntimeManager

Already supports runtime selection via factory injection:

constructor(
    private readonly manager: AppManager,
    private readonly runtimeFactory = defaultRuntimeFactory, // swap here
) {}

Only need a new NodeRuntimeSubprocessController implementing IRuntimeController + update the default factory (env var or config).

IPC performance (Node IPC vs stdio+msgpack)

• V8 structured clone replaces msgpack encode/decode on both sides → 20-40% serialization improvement
• Eliminates custom framing, Queue backpressure, extension codecs
• 5-15% overall improvement (serialization isn't the bottleneck)
• Recommendation: start with stdio for migration parity, add IPC as follow-up optimization

Key risks

1. ErrorEvent missing in Node — needs polyfill or different event pattern
2. import.meta.resolve() with Deno import maps — lib/require.ts critically depends on this
3. --experimental-transform-types is experimental — pin Node 22.7+ minimum
4. Network permission gap — no Node equivalent to --deny-net

Full plan at packages/apps-engine/node-runtime/MIGRATION_PLAN.md. Awaiting approval on decision points before implementation.

Original prompt

The directory @packages/apps-engine/deno-runtime contains code written for Deno to run apps in a subprocess.

I need you to analyze the code and plan a "node-runtime" that functions exactly the same but doesn't use Deno specific APIs.

Requirements:

• Use node's permissions API similarly to how we're using Deno's
• We want to use Node's built-in typescript support.
  List all potential problems we might face when switching runtimes.
• Evaluate what changes would be needed for the AppRuntimeManager to support selecting a different runtime.
• Evaluate whether there could be potential performance gains by using Node to Node IPC over stdio communication between Node and Deno

Write a plan and ask me for approval before executing

Custom agent used: Refactor Agent
A disciplined agent that performs code refactoring with a focus on improving code quality,
maintainability, and readability without changing external behavior. It ensures all tests
pass before and after changes, and creates incremental, reviewable PRs.

[dionisio-bot]

Looks like this PR is not ready to merge, because of the following issues:

• This PR is missing the 'stat: QA assured' label
• This PR is missing the required milestone or project
• This PR has an invalid title

Please fix the issues and try again

If you have any trouble, please check the PR guidelines

[changeset-bot]

⚠️ No Changeset found

Latest commit: 530e8b5

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR