Add linux-arm64 npm packaging

.github/workflows/PRLabelChecker.yml

@@ -1,7 +1,12 @@
 name: Label Checker
+# No `branches:` filter, for the same reason as ValidatePullRequests.yml.
+# `check-labels` is a required check on `main`, and base retargeting raises an
+# `edited` event, which is absent from the types below. A layer labelled while
+# it still targets the layer below would therefore never run this check, and
+# after retargeting nothing re-fires it, leaving a required check permanently
+# pending. Running on every base keeps the result attached to the head SHA.
 on:
   pull_request:
-    branches: main
     types: [opened, labeled, unlabeled, synchronize, reopened]
 permissions:
   pull-requests: read

.github/workflows/ValidatePullRequests.yml

@@ -2,9 +2,15 @@
 
 name: Validate Pull Request
 
+# No `branches:` filter: PRs in a stack target the layer below them rather than
+# `main`, and the filter is evaluated against the PR's own base ref, so a
+# filtered trigger leaves every stacked layer without build or test coverage
+# until the layer below merges and GitHub retargets it. That serialises all
+# breakage to merge time. `report-ci-status` is a required check on `main`, and
+# check runs attach to the head SHA, so running here means the result is already
+# present when a layer is retargeted.
 on:
   pull_request:
-    branches: [ main, 'release/**' ]
 
 # Cancels old running job if a new one is triggered (e.g. by a push onto the same branch).
 # This will cancel dependent jobs as well, such as dep_build and dep_benchmarks

.github/workflows/npm-publish.yml

@@ -44,7 +44,7 @@ env:
   # Comma-delimited npm package names that have not yet been published and
   # therefore cannot have a trusted publisher configured. Remove each package
   # in a follow-up PR after its first release and trusted-publisher setup.
-  FIRST_TIME_PACKAGES: ",@hyperlight-dev/js-host-api-darwin-arm64,"
+  FIRST_TIME_PACKAGES: ",@hyperlight-dev/js-host-api-darwin-arm64,@hyperlight-dev/js-host-api-linux-arm64-gnu,"
 
 jobs:
   build:
@@ -64,6 +64,9 @@ jobs:
           - target: aarch64-apple-darwin
             os: macos-15
             build_name: darwin-arm64
+          - target: aarch64-unknown-linux-gnu
+            os: [self-hosted, Linux, arm64, kvm]
+            build_name: linux-arm64-gnu
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v7
@@ -213,6 +216,12 @@ jobs:
           name: bindings-darwin-arm64
           path: ${{ env.WORKING_DIR }}/artifacts/darwin-arm64
 
+      - name: Download Linux arm64 GNU artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: bindings-linux-arm64-gnu
+          path: ${{ env.WORKING_DIR }}/artifacts/linux-arm64-gnu
+
       - name: Download JS bindings
         uses: actions/download-artifact@v8
         with:
@@ -230,10 +239,12 @@ jobs:
           mv artifacts/linux-x64-musl/*.node npm/linux-x64-musl/js-host-api.linux-x64-musl.node
           mv artifacts/win32-x64-msvc/*.node npm/win32-x64-msvc/js-host-api.win32-x64-msvc.node
           mv artifacts/darwin-arm64/*.node npm/darwin-arm64/js-host-api.darwin-arm64.node
+          mv artifacts/linux-arm64-gnu/*.node npm/linux-arm64-gnu/js-host-api.linux-arm64-gnu.node
           ls -la npm/linux-x64-gnu/
           ls -la npm/linux-x64-musl/
           ls -la npm/win32-x64-msvc/
           ls -la npm/darwin-arm64/
+          ls -la npm/linux-arm64-gnu/
 
       - name: Set package versions
         working-directory: ${{ env.WORKING_DIR }}
@@ -246,6 +257,7 @@ jobs:
           cd ../linux-x64-musl && npm version "$VERSION" --no-git-tag-version --allow-same-version
           cd ../win32-x64-msvc && npm version "$VERSION" --no-git-tag-version --allow-same-version
           cd ../darwin-arm64 && npm version "$VERSION" --no-git-tag-version --allow-same-version
+          cd ../linux-arm64-gnu && npm version "$VERSION" --no-git-tag-version --allow-same-version
         env:
           VERSION: ${{ inputs.version }}
 
@@ -325,6 +337,13 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ (github.event_name == 'workflow_dispatch' || contains(env.FIRST_TIME_PACKAGES, ',@hyperlight-dev/js-host-api-darwin-arm64,')) && secrets.NPM_TOKEN || '' }}
 
+      - name: Publish Linux arm64 GNU package
+        if: ${{ !inputs.dry_run }}
+        working-directory: ${{ env.WORKING_DIR }}/npm/linux-arm64-gnu
+        run: npm publish --access public --ignore-scripts ${{ (github.event_name == 'workflow_dispatch' || contains(env.FIRST_TIME_PACKAGES, ',@hyperlight-dev/js-host-api-linux-arm64-gnu,')) && '' || '--provenance' }}
+        env:
+          NODE_AUTH_TOKEN: ${{ (github.event_name == 'workflow_dispatch' || contains(env.FIRST_TIME_PACKAGES, ',@hyperlight-dev/js-host-api-linux-arm64-gnu,')) && secrets.NPM_TOKEN || '' }}
+
       - name: Publish main package
         if: ${{ !inputs.dry_run }}
         working-directory: ${{ env.WORKING_DIR }}
@@ -342,7 +361,8 @@ jobs:
                      "@hyperlight-dev/js-host-api-linux-x64-gnu" \
                      "@hyperlight-dev/js-host-api-linux-x64-musl" \
                      "@hyperlight-dev/js-host-api-win32-x64-msvc" \
-                     "@hyperlight-dev/js-host-api-darwin-arm64"; do
+                     "@hyperlight-dev/js-host-api-darwin-arm64" \
+                     "@hyperlight-dev/js-host-api-linux-arm64-gnu"; do
             if npm view "$pkg@$VERSION" version > /dev/null 2>&1; then
               echo "✅ $pkg@$VERSION published"
             else
@@ -375,5 +395,8 @@ jobs:
           echo "--- @hyperlight-dev/js-host-api-darwin-arm64 ---"
           npm pack ./npm/darwin-arm64 --dry-run
           echo ""
+          echo "--- @hyperlight-dev/js-host-api-linux-arm64-gnu ---"
+          npm pack ./npm/linux-arm64-gnu --dry-run
+          echo ""
           echo "--- @hyperlight-dev/js-host-api ---"
           npm pack --dry-run

Justfile

@@ -226,12 +226,13 @@ set-version version:
     cargo update \
         --manifest-path src/hyperlight-js-runtime/tests/fixtures/extended_runtime/Cargo.toml \
         -p hyperlight-js-runtime -p hyperlight-js-common
-    # npm: main + the 4 platform package.json versions (--ignore-scripts avoids needing node_modules)
+    # npm: main + the 5 platform package.json versions (--ignore-scripts avoids needing node_modules)
     cd src/js-host-api && npm version {{ version }} --no-git-tag-version --allow-same-version --ignore-scripts
     cd src/js-host-api/npm/linux-x64-gnu && npm version {{ version }} --no-git-tag-version --allow-same-version --ignore-scripts
     cd src/js-host-api/npm/linux-x64-musl && npm version {{ version }} --no-git-tag-version --allow-same-version --ignore-scripts
     cd src/js-host-api/npm/win32-x64-msvc && npm version {{ version }} --no-git-tag-version --allow-same-version --ignore-scripts
     cd src/js-host-api/npm/darwin-arm64 && npm version {{ version }} --no-git-tag-version --allow-same-version --ignore-scripts
+    cd src/js-host-api/npm/linux-arm64-gnu && npm version {{ version }} --no-git-tag-version --allow-same-version --ignore-scripts
     # Verify the npm lockfile
     cd src/js-host-api && npm ci --dry-run --omit=optional --ignore-scripts
 

docs/release.md

@@ -10,7 +10,7 @@ Do this with the `just set-version` recipe. **Always use this instead of bumping
 
 - every workspace crate's `version` and the root `Cargo.lock`,
 - the excluded `extended_runtime` fixture's own `Cargo.lock` (a bare `cargo set-version` can't reach it, and a stale one fails the `native_modules --locked` build),
-- the npm main package and the three platform packages,
+- the npm main package and the five platform packages,
 - the root package version in `src/js-host-api/package-lock.json`.
 
 Keep `optionalDependencies` on the latest published version so `npm ci` can use
@@ -68,12 +68,13 @@ Trusted publishing is configured on [npmjs.com](https://www.npmjs.com/) for each
 3. Set **Organization**: `hyperlight-dev`, **Repository**: `hyperlight-js`, **Workflow**: `CreateRelease.yml`
 4. Save
 
-This must be done for all 5 packages:
+This must be done for all 6 packages:
 - `@hyperlight-dev/js-host-api`
 - `@hyperlight-dev/js-host-api-linux-x64-gnu`
 - `@hyperlight-dev/js-host-api-linux-x64-musl`
 - `@hyperlight-dev/js-host-api-win32-x64-msvc`
 - `@hyperlight-dev/js-host-api-darwin-arm64`
+- `@hyperlight-dev/js-host-api-linux-arm64-gnu`
 
 > **Note:** Trusted publishers are configured per package, and npm cannot configure one for a
 > package that does not exist yet. The publish workflow therefore has a temporary
@@ -113,12 +114,13 @@ If you need to publish npm packages manually via `workflow_dispatch`, you'll nee
 1. **Temporarily allow token-based publishing on npmjs.com**
    - Go to each package on [npmjs.com](https://www.npmjs.com/) → Settings → Publishing access
    - Change from "Require two-factor authentication and disallow tokens" to "Require two-factor authentication or automation tokens"
-   - Do this for all 5 packages:
+   - Do this for all 6 packages:
      - `@hyperlight-dev/js-host-api`
      - `@hyperlight-dev/js-host-api-linux-x64-gnu`
      - `@hyperlight-dev/js-host-api-linux-x64-musl`
      - `@hyperlight-dev/js-host-api-win32-x64-msvc`
      - `@hyperlight-dev/js-host-api-darwin-arm64`
+     - `@hyperlight-dev/js-host-api-linux-arm64-gnu`
 
 2. **Create an npm automation token**
    - Go to [npmjs.com](https://www.npmjs.com/) → Access Tokens → Generate New Token → Granular Access Token
@@ -140,5 +142,5 @@ If you need to publish npm packages manually via `workflow_dispatch`, you'll nee
 5. **Clean up immediately after publishing**
    - Delete the `NPM_TOKEN` repo secret on GitHub → Settings → Secrets and variables → Actions
    - Revoke the npm token on npmjs.com → Access Tokens
-   - Re-enable "Require two-factor authentication and disallow tokens" on all 5 packages
+   - Re-enable "Require two-factor authentication and disallow tokens" on all 6 packages
    - Verify the packages published correctly: `npm view @hyperlight-dev/js-host-api versions`

src/js-host-api/DEVELOPMENT.md

@@ -67,6 +67,7 @@ The npm release consists of the following packages:
 | `@hyperlight-dev/js-host-api-linux-x64-musl` | Linux x86_64 (musl/Alpine) native binary |
 | `@hyperlight-dev/js-host-api-win32-x64-msvc` | Windows x86_64 native binary |
 | `@hyperlight-dev/js-host-api-darwin-arm64` | macOS aarch64 (Apple Silicon) native binary |
+| `@hyperlight-dev/js-host-api-linux-arm64-gnu` | Linux aarch64 (glibc) native binary |
 
 ### How Platform Selection Works
 

src/js-host-api/npm/linux-arm64-gnu/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hyperlight-dev/js-host-api-linux-arm64-gnu",
+  "version": "0.4.0",
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "main": "js-host-api.linux-arm64-gnu.node",
+  "files": [
+    "js-host-api.linux-arm64-gnu.node"
+  ],
+  "description": "Node.js API bindings for Hyperlight JS - Linux arm64 gnu",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyperlight-dev/hyperlight-js.git"
+  },
+  "homepage": "https://github.com/hyperlight-dev/hyperlight-js#readme",
+  "bugs": {
+    "url": "https://github.com/hyperlight-dev/hyperlight-js/issues"
+  },
+  "engines": {
+    "node": ">= 18"
+  },
+  "libc": [
+    "glibc"
+  ]
+}

src/js-host-api/package.json

@@ -31,12 +31,14 @@
       "x86_64-unknown-linux-gnu",
       "x86_64-unknown-linux-musl",
       "x86_64-pc-windows-msvc",
-      "aarch64-apple-darwin"
+      "aarch64-apple-darwin",
+      "aarch64-unknown-linux-gnu"
     ]
   },
   "license": "Apache-2.0",
   "optionalDependencies": {
     "@hyperlight-dev/js-host-api-darwin-arm64": "0.4.0",
+    "@hyperlight-dev/js-host-api-linux-arm64-gnu": "0.4.0",
     "@hyperlight-dev/js-host-api-linux-x64-gnu": "0.4.0",
     "@hyperlight-dev/js-host-api-linux-x64-musl": "0.4.0",
     "@hyperlight-dev/js-host-api-win32-x64-msvc": "0.4.0"