require() of ESM-only deps (https-proxy-agent, cli-cursor) breaks on Node >=20 when require(esm) is disabled; declared Node 24 support is untested

[julia-miller-eng]

Summary

@osls/compose declares support for Node 24 (engines: "^20.19.0 || ^22.13.0 || >=24") but require()s ESM-only dependencies:

• src/utils/aws/config.js:3 → const { HttpsProxyAgent } = require('https-proxy-agent'); (https-proxy-agent@^9.0.0, ESM-only)
• src/cli/Progresses.js:9 → const cliCursor = require('cli-cursor').default; (cli-cursor@^5.0.0, ESM-only)

These only load because Node ≥22.12 / 24 enables require(esm) by default — an experimental feature. As a result the CLI:

1. emits ExperimentalWarning: Support for loading ES Module in require() is an experimental feature on every run, and
2. crashes with ERR_REQUIRE_ESM whenever require(esm) is turned off — e.g. --no-experimental-require-module, a legitimate/supported setting (and the default before Node flipped it), commonly applied via NODE_OPTIONS or an .npmrc node-options= entry.

Reproduction

# Node 24.x
node --no-experimental-require-module \
  -e "require('@osls/compose/src/cli/Progresses.js')"

or, in any project whose .npmrc/env disables the flag:

npx sls <service>:deploy

Actual:

Error [ERR_REQUIRE_ESM]: require() of ES Module .../cli-cursor/index.js
from .../@osls/compose/src/cli/Progresses.js not supported.
Instead change the require of index.js to a dynamic import() ...

Once one such dependency is worked around, the next (https-proxy-agent) throws — i.e. there are multiple affected require() sites.

Expected: the CLI runs on Node 24 regardless of the require(esm) flag state, without relying on an experimental feature.

Why CI doesn't catch it

.github/workflows/tests.yml runs unit tests only on Node 20 and 22; the Node 24 job runs only formatting/lint + pack-smoke.js. No test exercises the require()-of-ESM code path on the version being advertised as supported.

Suggested fixes

• Load these ESM-only deps via dynamic import(), or pin CJS-compatible versions (https-proxy-agent@7, cli-cursor@3), so loading never depends on require(esm).
• Add a Node 24 unit-test job (ideally one also run with --no-experimental-require-module) to prevent regressions.

Environment

• @osls/compose 1.9.1 (npm) / osls 4.0.0
• Node 24.18.0, npm 11.x, Linux (GitHub Actions ubuntu-latest); also reproduced on macOS.

[GrahamCampbell]

Thanks for the detailed report — I did go through it carefully, but I don't think it holds up. I can't reproduce the ExperimentalWarning anywhere: I tried Node 20.19, 22.21 and 24.14 with stderr captured, and there's no warning on any of them. That's expected, because the warning was removed in v20.19.0 and v22.13.0, which is exactly why our engines range is ^20.19.0 || ^22.13.0 || >=24 — and on the 24.18.0 you're running, require(esm) isn't even experimental any more, having gone stable in 24.15.0. The reliance on require(esm) is deliberate, not something that snuck in: we tightened engines to ^22.13.0 in #11 before adopting the ESM-only deps in #20 and #22, and every Node version where the feature is off by default is already excluded.

That means the only way to hit the crash is to pass --no-experimental-require-module yourself. That's opting out of a feature that's on by default everywhere we support (and stable on current Node 24), and no package survives having a feature it depends on switched off. If something in your setup injects that flag via NODE_OPTIONS or .npmrc, I'd fix it there rather than have us pin back to CJS-era dependency versions.

On the CI point, this path is exercised on Node 24 already. That job isn't just lint: scripts/ci/pack-smoke.js packs the real tarball, installs it into a clean project and runs osls-compose --help, which loads both https-proxy-agent and cli-cursor (I checked by instrumenting the loader), so it runs on every PR. Given all that, I'm not planning to downgrade the deps or convert to dynamic import(). If you're seeing ERR_REQUIRE_ESM without the flag, that points at Node <20.19, which is outside the supported range — but happy to take another look if you have a repro where the flag genuinely isn't involved.

[julia-miller-eng]

@GrahamCampbell thanks for your response and super sorry about wasting your time on it - should have checked our own config before filing the request 🙈
The root cuase was a node-options='--no-experimental-require-module' line sitting in our project's .npmrc - it forced the flag off for every npm/npx-spawned process, so sls hit ERR_REQUIRE_ESM 😅
Meaning, you're right on both counts, apologies again for the noise, and thanks for the thorough, patient response 🙏