dsh web fails on OpenHarmony/arm64: No usable native binding found for node-addon-require-builtin-openharmony-arm64

[zixuan-chen]

Summary

On HarmonyOS PC (OpenHarmony, arm64, musl), the dsh CLI installs fine and
dsh --version / dsh --help work, but every profile-booting command fails
(dsh web, dsh tui, dsh headless, and even
dsh --profile web --dump-config-schema).

The failure comes from the native loader
node-addon-native-custom-loader → node-addon-require-builtin, which has no
binding for this platform.

Environment

Item	Value
OS	HarmonyOS PC (OpenHarmony), HongMeng Kernel 1.13.0
process.platform	openharmony
process.arch	arm64
libc	musl (/lib/ld-musl-aarch64.so.1; process.report().header.glibcVersionRuntime is undefined, no glibc present)
dsh version	0.1.7-rc.2 (npm @deepseek-ai/dsh)
node-addon-require-builtin	0.1.6
Node.js (attempt 1)	v24.13.0 — ABI/modules 137
Node.js (attempt 2)	v26.10.0 — ABI/modules 147

Both Node versions fail identically, so this is not an ABI mismatch but a
missing platform target.

Steps to reproduce

npm i -g @deepseek-ai/dsh
dsh --version          # works: 0.1.7-rc.2
dsh web                # fails

Actual behavior

dsh: fatal uncaught exception: Error: dsh: host preparation failed:
No usable native binding found for node-addon-require-builtin-openharmony-arm64 (auto)
    at boot (.../@deepseek-ai/dsh-app-boot/lib/index.js:4104:9)
    at async runProfile (.../@deepseek-ai/dsh/lib/profile-boot-BZ2ZjNWi.js:271:15)
    at async runCli (.../@deepseek-ai/dsh/lib/bin.js:212:5)

The loader reports three failed attempts:

1. source: 'optional-package', request
   node-addon-require-builtin-openharmony-arm64 → MODULE_NOT_FOUND
2. source: 'local-build', path
   .../node-addon-require-builtin/build/nodeabi/node-v147-openharmony-arm64/require_builtin.node
   → MODULE_NOT_FOUND
3. source: 'local-build', path
   .../node-addon-require-builtin/build/napi/napi-v9-openharmony-arm64/require_builtin.node
   → MODULE_NOT_FOUND

Root cause

node-addon-require-builtin@0.1.6 declares these optionalDependencies:

node-addon-require-builtin-darwin-arm64
node-addon-require-builtin-darwin-x64
node-addon-require-builtin-linux-arm64-gnu
node-addon-require-builtin-linux-x64-gnu
node-addon-require-builtin-win32-arm64-msvc
node-addon-require-builtin-win32-x64-msvc
node-addon-require-builtin-win32-ia32-msvc

There is no openharmony entry, and per the package README, published installs
"do not ship native sources and fail closed" — so no local compilation fallback
either.

In node-addon-native-custom-loader/lib/index.js:

function runtimeSuffix() {
    if (process.platform === 'darwin') return `darwin-${process.arch}`;
    if (process.platform === 'linux') {
        const libc = linuxLibc() === 'glibc' ? 'gnu' : 'musl';
        return `linux-${process.arch}-${libc}`;
    }
    if (process.platform === 'win32') return `win32-${process.arch}-msvc`;
    return `${process.platform}-${process.arch}`;   // → "openharmony-arm64"
}

So the requested suffix is openharmony-arm64, which no package provides. The
only escape hatch exposed is NARB_BACKEND (chooses napi vs nodeabi); there
is no environment variable to override the platform/libc suffix
(NARB_DISABLE_OPTIONAL_PACKAGE, NARB_DISABLE_LOCAL_BUILD,
NARB_DISABLE_NATIVE_CACHE, NARB_NATIVE_CACHE_DIR are the others, none of
which help).

Note: this also affects musl Linux

runtimeSuffix() already models a musl variant (linux-arm64-musl), but no
musl package is published — only *-gnu. Alpine Linux and other musl distros
should hit the same dead end. Fixing the musl gap therefore helps more than
just OpenHarmony.

Suggested fixes (in order of effort)

1. Publish node-addon-require-builtin-openharmony-arm64 (musl, Node-API).
   OpenHarmony's kernel exposes a Linux-compatible syscall ABI, so a
   musl-targeted N-API build is likely to load as-is, especially for the
   napi backend (ABI-stable, no per-Node-version rebuild).
   Bonus: also ship node-addon-require-builtin-linux-{x64,arm64}-musl — the
   same artifact, tested on Alpine.
2. Add a platform override escape hatch, e.g.
   NARB_PLATFORM_OVERRIDE=linux-arm64-musl, so advanced users on
   unreleased-for platforms can borrow a compatible binding instead of getting
   a hard failure. This is cheap and unblocks any future niche platform
   without a release cycle.
3. Graceful degradation: if the loader cannot find any binding, fall back
   to a pure-JS path (or a clear "unsupported platform" diagnostic) rather
   than an uncaught exception during host preparation.

Workarounds tried

• Installing under two different Node major versions (24 / 26) — same failure.
• Installing into a user-local prefix outside the app sandbox — same failure.
• NARB_BACKEND=napi and NARB_BACKEND=nodeabi — same failure (both need a
  openharmony-arm64 artifact that does not exist).

Currently no dsh profile can boot on this platform; only --version and
--help work, since they do not load native bindings.

Additional context

Node.js itself is not an OpenHarmony target upstream; it reaches these devices
through community distributions (here: harmonybrew, which ships a
prebuilt musl Node for OpenHarmony/arm64). I understand supporting a platform
that upstream Node does not officially target may be out of scope — in that
case, option 2 (a documented platform override) alone would let the community
self-serve without a formal support commitment. Happy to test any candidate
musl/arm64 build on this machine and report back.

[JounQin]

For me, it's node-addon-require-builtin-linux-x64-musl.

[danilinao]

Same for node-addon-require-builtin-linux-x64-gnu

[JounQin]

Same for node-addon-require-builtin-linux-x64-gnu

Are you sure? https://www.npmjs.com/package/node-addon-require-builtin-linux-x64-gnu is available, I changed my Dockerfile to use gnu version and it works well.