[John-David Dalton (jdalton)]

Install only the native binaries needed by the current OS and CPU, addressing #864 with the optional-package approach used by @lydell/node-pty. In the measured macOS ARM64 example, wrapper plus native package fall from 26.9 MB to 2.67 MB unpacked and 7.15 MB to 1.25 MB downloaded, while retaining source-build fallback.

Fixes #864. This is the per-platform distribution option. The alternative is #1015, which keeps the existing distribution and compresses its native addons. Both address the package-size overhead discussed in #864, with different savings and tradeoffs. These are independent proposals; maintainers can choose either approach.

Package and loader changes

• Generate six exact-version optional packages under @node-pty, with OS/CPU constraints and glibc metadata for Linux.
• Preserve the public node-pty API, source Release/Debug precedence, and legacy prebuild directories.
• Resolve optional packages to their real directories so macOS helpers and Windows DLLs stay beside their addons.
• Keep source-build inputs in the wrapper, including Windows third-party assets. Forced source builds do not delete optional-package contents.
• Detect musl even when a package manager ignores the libc field.
• Include runtime assets only in native packages; omit PDB debug symbols.
• Native image headers must match the advertised target.
• This branch is independent of the native-compression proposal.

Build and publication workflows

Lydell provides build/publish scripts rather than a GitHub workflow. This adds a manual six-platform workflow that builds and tests native packages, packs all seven tarballs, and tests actual installs with lifecycle scripts disabled before allowing publication.

The opt-in upstream-main publish job uses npm trusted publishing and a protected npm environment. It verifies every tarball's SHA-512, publishes native packages before the wrapper, stops on failures, and only skips already-published versions when their integrity matches.

Azure build/test/scan configuration remains; its old publish switch is removed to prevent independent publication of the monolithic wrapper. The new GitHub release job does not automatically inherit Azure organizational approval/security gates.

Maintainer setup is required: ownership/bootstrap of the proposed scope and six package names, npm trusted publishing for seven packages, and the protected environment/release gates. No npm packages or account settings were changed.

Release workflow and local reproduction.

Measurements and validation

The size example uses node-pty 1.2.0-beta.18 native builds with this branch's wrapper. The macOS ARM64 package pair contains 2,674,852 unpacked bytes and 1,251,650 tarball bytes. Savings include removing debug symbols as well as other platforms; shared dependencies and filesystem allocation are excluded.

Per-package sizes.

• TypeScript build and ESLint passed; existing macOS suite: 24 passed.
• Platform-package suite: six passed on macOS ARM64 and Linux ARM64, including real optional-package PTY spawning, source fallback, manifest checks, publication ordering/failure handling, and resumability.
• All six packages and the wrapper were packed locally from published native inputs.
• Actual wrapper/native tarball installation with scripts disabled and real PTY spawning passed on macOS ARM64 and Linux ARM64.
• New release workflow passed actionlint.
• Windows/x64 execution, the complete upstream workflow, pnpm/Yarn, and actual npm publication remain unverified. Cross-platform CI and maintainer release setup remain outstanding.

[John-David Dalton (jdalton)]

@microsoft-github-policy-service agree

[John-David Dalton (jdalton)]

\cc Simon Lydell (@lydell)

[John-David Dalton (jdalton)]

I actually think #1018 is the way to avoid most of this, it leverages Node FFI in Node 26 (LTS now).
Feel free to keep this PR as reference.