Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -83,3 +83,6 @@ jobs:

- name: Test
run: npm test

- name: Test platform packages and real PTY loading
run: npm run test:platforms
161 changes: 161 additions & 0 deletions .github/workflows/platform-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
name: Platform package release
on:
workflow_dispatch:
inputs:
version:
description: 'Exact release version (for example 1.2.0-beta.19)'
required: true
type: string
tag:
description: npm distribution tag
type: choice
options: [beta, latest]
default: beta
publish:
description: Publish verified tarballs to npm
type: boolean
default: false
permissions:
contents: read
concurrency:
group: node-pty-npm-release
cancel-in-progress: false
jobs:
build:
name: Build ${{ matrix.target }}
strategy:
fail-fast: false
matrix:
include:
- { os: ubuntu-22.04, target: linux-x64, arch: x64 }
- { os: ubuntu-22.04-arm, target: linux-arm64, arch: arm64 }
- { os: macos-14, target: darwin-arm64, arch: arm64 }
- { os: macos-15-intel, target: darwin-x64, arch: x64 }
- { os: windows-2022, target: win32-x64, arch: x64 }
- { os: windows-11-arm, target: win32-arm64, arch: arm64 }
runs-on: ${{ matrix.os }}
env:
RELEASE_VERSION: ${{ inputs.version }}
ARCH: ${{ matrix.arch }}
npm_config_arch: ${{ matrix.arch }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24.22.1'
- name: Validate release version
run: node -e "require('./scripts/platform-packages').validateVersion(process.env.RELEASE_VERSION)"
- name: Install Linux sysroot
if: runner.os == 'Linux'
shell: bash
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
set -euo pipefail
sudo apt-get update -qq
sudo apt-get install -y gcc-10 g++-10
echo 'CC=gcc-10' >> "$GITHUB_ENV"
echo 'CXX=g++-10' >> "$GITHUB_ENV"
SYSROOT_PATH=$(node scripts/linux/install-sysroot.js "$ARCH" | grep 'SYSROOT_PATH=' | cut -d= -f2)
echo "SYSROOT_PATH=$SYSROOT_PATH" >> "$GITHUB_ENV"
- run: npm ci
- run: npm test
- run: npm run test:platforms
- name: Verify glibc compatibility
if: runner.os == 'Linux'
shell: bash
run: EXPECTED_GLIBC_VERSION=2.28 EXPECTED_GLIBCXX_VERSION=3.4.25 SEARCH_PATH=build ./scripts/linux/verify-glibc-requirements.sh
- name: Stage native package
shell: bash
run: npm run package:platforms -- platform release "$RELEASE_VERSION" '${{ matrix.target }}'
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
with:
name: native-${{ matrix.target }}
path: release/${{ matrix.target }}/
if-no-files-found: error
pack:
needs: build
runs-on: ubuntu-22.04
env:
RELEASE_VERSION: ${{ inputs.version }}
RELEASE_TAG: ${{ inputs.tag }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24.22.1'
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
with:
pattern: native-*
path: artifacts
- name: Assemble all platforms
shell: bash
run: |
mkdir release
for source in artifacts/native-*; do
target=${source#artifacts/native-}
mv "$source" "release/$target"
done
chmod +x release/darwin-*/spawn-helper
- run: npm ci --ignore-scripts
- run: npm run build
- name: Pack and verify complete release
run: |
npm run package:platforms -- release release "$RELEASE_VERSION"
npm run publish:platforms -- release/tarballs "$RELEASE_TAG"
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
with:
name: npm-release
path: release/tarballs/
if-no-files-found: error
verify-install:
needs: pack
strategy:
fail-fast: false
matrix:
os: [ubuntu-22.04, ubuntu-22.04-arm, macos-14, macos-15-intel, windows-2022, windows-11-arm]
runs-on: ${{ matrix.os }}
env:
RELEASE_TAG: ${{ inputs.tag }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24.22.1'
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
with:
name: npm-release
path: tarballs
- name: Install tarballs without scripts and spawn a real PTY
shell: bash
run: npm run test:release -- tarballs "$RELEASE_TAG"
publish:
needs: verify-install
if: inputs.publish && github.repository == 'microsoft/node-pty' && github.ref == 'refs/heads/main'
runs-on: ubuntu-22.04
environment: npm
permissions:
contents: read
id-token: write
env:
RELEASE_TAG: ${{ inputs.tag }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24.22.1'
registry-url: https://registry.npmjs.org
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
with:
name: npm-release
path: tarballs
- name: Publish native packages, then node-pty
run: npm run publish:platforms -- tarballs "$RELEASE_TAG" --publish
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,5 @@ fixtures/space folder/
yarn.lock
prebuilds/
_codeql_detected_source_root

release/
47 changes: 47 additions & 0 deletions docs/platform-package-sizes.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
{
"input": "node-pty@1.2.0-beta.18 native prebuilds; current branch JS wrapper; package-file sizes excluding dependencies and filesystem allocation",
"packages": [
{
"name": "node-pty",
"version": "1.2.0-beta.19",
"tarballBytes": 1227892,
"unpackedBytes": 2533645
},
{
"name": "@node-pty/darwin-arm64",
"version": "1.2.0-beta.19",
"tarballBytes": 23758,
"unpackedBytes": 141207
},
{
"name": "@node-pty/darwin-x64",
"version": "1.2.0-beta.19",
"tarballBytes": 23666,
"unpackedBytes": 71719
},
{
"name": "@node-pty/linux-arm64",
"version": "1.2.0-beta.19",
"tarballBytes": 27050,
"unpackedBytes": 72924
},
{
"name": "@node-pty/linux-x64",
"version": "1.2.0-beta.19",
"tarballBytes": 28980,
"unpackedBytes": 75604
},
{
"name": "@node-pty/win32-arm64",
"version": "1.2.0-beta.19",
"tarballBytes": 755734,
"unpackedBytes": 1625457
},
{
"name": "@node-pty/win32-x64",
"version": "1.2.0-beta.19",
"tarballBytes": 831075,
"unpackedBytes": 1604537
}
]
}
96 changes: 96 additions & 0 deletions docs/platform-packages.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Platform-specific packages

This implements [node-pty #864](https://github.com/microsoft/node-pty/issues/864)
using the optional-package model from [@lydell/node-pty](https://github.com/lydell/node-pty).
The public `node-pty` entry point and types stay the same. Exact-version optional
dependencies select `@node-pty/<os>-<cpu>` for Darwin, Linux, and Windows, on ARM64
and x64. Linux packages declare glibc, matching the existing 2.28 sysroot; the
install script also detects musl for package managers that ignore `libc`.

Unlike Lydell's prebuilt-only distribution, the wrapper keeps the source and
Windows `third_party` assets needed for node-gyp. Source builds, `--omit=optional`,
and `npm_config_build_from_source=true` remain supported. A forced source build
never removes files from an optional package shared by a package manager. Local
Release/Debug builds and legacy `prebuilds/` directories retain loading priority.

Native packages contain only runtime `.node` files, macOS `spawn-helper`, and
Windows `conpty/` files. They omit PDB debug symbols and have no install scripts.
The loader resolves the package's absolute directory so helper and DLL paths work
with hoisted dependencies and symlinked package-manager layouts. `--ignore-scripts`
works when the matching optional package is installed. Without optional packages
and without build scripts, native loading cannot work.

## Release workflow

Lydell's repository has build and publish scripts; its publish script publishes
native packages before the wrapper. `.github/workflows/platform-release.yml`
implements that order with native builds and real installed-tarball tests:

1. Dispatch with an explicit version and `beta` or `latest` tag. Publishing is off
by default. Inputs are validated and passed through environment variables.
2. Six native runners build and run node-pty's tests. Linux uses the existing
sysroot and glibc checks. Platform tests exercise real PTY spawning through an
isolated optional package. Native headers must match their advertised target.
3. A packaging job checks that all six packages have matching versions and target
constraints. It generates the wrapper with exact optional dependency versions,
then creates seven tarballs and a SHA-512 release manifest.
4. Six runners install the actual matching tarball and wrapper with install scripts
disabled, then spawn a PTY. Publication depends on all six passing.
5. An opt-in job on upstream `main`, protected by the `npm` environment, checks
every tarball hash and publishes the six native packages before `node-pty`.
Publication stops on any failure. Reruns skip versions only when npm reports
identical tarball integrity; differing published bytes abort the release.

Azure's existing build/test/scan pipeline remains, but its publish switch is
removed to prevent it from publishing a monolithic wrapper independently. Its
checks are separate from the new GitHub release workflow; existing organizational
release/security gates must also be configured for the new `npm` environment.

### Maintainer setup

The `@node-pty` scope and six package names must be owned by the maintainers.
Configure npm trusted publishing for all seven packages to this repository,
`platform-release.yml`, and environment `npm`. New package bootstrap and protected
environment approvals require maintainer access. No npm packages, credentials,
or environments are created by this PR. The workflow requests OIDC only in the
publish job; dry runs and fork tests cannot publish. Download the `npm-release`
artifact to inspect the exact tarballs before enabling publication.

### Local commands

After `npm ci`, build one platform package:

```sh
npm run package:platforms -- platform release 1.2.0-beta.19 darwin-arm64
```

Collect all six platform directories under `release/`, then:

```sh
npm run package:platforms -- release release 1.2.0-beta.19
npm run publish:platforms -- release/tarballs beta
npm run test:release -- release/tarballs beta
```

The publish command is a dry run unless `--publish` is explicitly supplied. The
packed smoke test uses the current platform. `npm run test:platforms` covers
version/target rejection, incomplete releases, package metadata, integrity and
publish ordering, source fallback, and real native loading. npm is used for the
installed-tarball tests; pnpm/Yarn and a real npm publication need separate release
validation.

## Size example

Using the six native builds from node-pty 1.2.0-beta.18 and this branch's wrapper,
the macOS ARM64 installation contains 2,674,852 bytes across its two packages,
versus the beta's 26,907,504 bytes (90.1% less). The two tarballs total 1,251,650
bytes versus 7,152,900 bytes (82.5% less). These are package-file sums, excluding
shared dependencies and filesystem allocation. The result includes omitting PDB
symbols as well as omitting other platforms; it is not solely a platform-filtering
measurement. The wrapper retains about 2.5 MB including source-build assets.

The exact local release was dry-run validated and its wrapper/native tarballs
were installed with scripts disabled and used to spawn a real PTY on macOS ARM64.
The six-platform workflow still needs upstream execution and npm/environment setup.

[Per-package measurements](platform-package-sizes.json) include all six targets.
6 changes: 5 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,11 @@
"test": "cross-env NODE_ENV=test mocha -R spec --exit lib/*.test.js",
"posttest": "npm run lint",
"prepare": "npm run build",
"prepublishOnly": "npm run build"
"prepublishOnly": "npm run build",
"package:platforms": "node scripts/platform-packages.js",
"test:platforms": "mocha --exit test/platform-packages.js",
"publish:platforms": "node scripts/publish-platform-packages.js",
"test:release": "node scripts/test-platform-release.js"
},
"dependencies": {
"node-addon-api": "^7.1.0"
Expand Down
8 changes: 3 additions & 5 deletions publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,6 @@ resources:
endpoint: Monaco

parameters:
- name: publishPackage
displayName: 🚀 Publish node-pty
type: boolean
default: false
- name: releaseQuality
displayName: Quality
type: string
Expand Down Expand Up @@ -91,7 +87,9 @@ extends:
- script: npm run lint
displayName: 'Lint'

publishPackage: ${{ parameters.publishPackage }}
# Publishing moved to .github/workflows/platform-release.yml so all
# native packages are published before the wrapper. Keep Azure checks.
publishPackage: false
${{ if eq(variables['releaseQuality'], 'stable') }}:
tag: latest
publishRequiresApproval: true
Expand Down
21 changes: 21 additions & 0 deletions scripts/native-target.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
// Copyright (c) Microsoft Corporation. Licensed under the MIT License.
// Check the compiler artifact before labeling a package with a platform/CPU.
// The native loader still validates the complete image and its signature.
function verifyNativeTarget(bytes, target) {
const [platform, arch] = target.split('-');
let valid = false;
if (bytes.length >= 64 && (arch === 'arm64' || arch === 'x64')) {
if (platform === 'linux') {
valid = bytes.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])) &&
bytes[4] === 2 && bytes[5] === 1 && bytes.readUInt16LE(18) === (arch === 'arm64' ? 183 : 62);
} else if (platform === 'darwin') {
valid = bytes.readUInt32LE(0) === 0xfeedfacf && bytes.readUInt32LE(4) === (arch === 'arm64' ? 0x100000c : 0x1000007);
} else if (platform === 'win32') {
const offset = bytes.readUInt32LE(0x3c);
valid = bytes[0] === 0x4d && bytes[1] === 0x5a && offset <= bytes.length - 6 &&
bytes.readUInt32LE(offset) === 0x4550 && bytes.readUInt16LE(offset + 4) === (arch === 'arm64' ? 0xaa64 : 0x8664);
}
}
if (!valid) { throw new Error(`Native image does not match ${target}`); }
}
module.exports = { verifyNativeTarget };
Loading