Add linux-arm64 npm packaging by simongdavies · Pull Request #310 · hyperlight-dev/hyperlight-js

simongdavies · 2026-09-16T20:36:02Z

Layer 2 of a stacked PR — based on #308, not main.

Adds npm packaging for linux-arm64, completing the npm side of the aarch64 support started in #308. Layer 1 added the aarch64-apple-darwin package and the Linux aarch64 CI matrix but deliberately stopped short of Linux arm64 npm packaging; this is that piece.

Review note: the diff shown against main will include #308's commits until that merges. The only commit belonging to this PR is 252ab33.

What this adds

A new @hyperlight-dev/js-host-api-linux-arm64-gnu platform package, mirroring the existing linux-x64-gnu conventions exactly:

Field	Value
`os`	`["linux"]`
`cpu`	`["arm64"]`
`libc`	`["glibc"]`
target	`aarch64-unknown-linux-gnu`
runner	`[self-hosted, Linux, arm64, kvm]`

There is no musl aarch64 variant — glibc only, matching the scope of the existing Linux packages.

Wired through: npm/linux-arm64-gnu/package.json (new), the main package.json (napi.targets + optionalDependencies), package-lock.json, npm-publish.yml (matrix, artifact download, staging, versioning, publish, verification, dry-run), the set-version recipe in Justfile, docs/release.md and src/js-host-api/DEVELOPMENT.md.

Notes

FIRST_TIME_PACKAGES. The new package is added to this list because npm cannot configure a trusted publisher for a package that does not exist yet, so its first release must use NPM_TOKEN. It should be removed in a follow-up PR after the first publish, per the procedure already documented in docs/release.md.

Lockfile. As with darwin-arm64 in #308, the root lock edge has no resolved URL and no integrity hash — unavoidable until the package is first published. npm ci silently skips unresolvable optional deps. The lockfile was hand-edited rather than regenerated, so the diff is exactly one line and no libc fields were stripped (npm 10.9.3 does that on regeneration).

Doc fix. docs/release.md said "the npm main package and the three platform packages" when there were already four; corrected straight to five here rather than in #308 to avoid a guaranteed same-line conflict between the two layers.

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com

Adds the `@hyperlight-dev/js-host-api-linux-arm64-gnu` platform package so Linux aarch64 consumers get a prebuilt native binary, completing the npm side of aarch64 support. Mirrors the existing `linux-x64-gnu` package conventions: `os: [linux]`, `cpu: [arm64]`, `libc: [glibc]`. There is no musl aarch64 variant. The publish matrix builds `aarch64-unknown-linux-gnu` on `[self-hosted, Linux, arm64, kvm]`, matching the Linux aarch64 runner labels already used by dep_build.yml. That target is native on those runners, so unlike the musl entry it needs no extra `rustup target add`. The new package is added to FIRST_TIME_PACKAGES because it has no npm trusted publisher until it is published once. As with darwin-arm64, its root lockfile edge has no `resolved` URL or `integrity` hash until the first release; `npm ci` skips unresolvable optional deps, and this was verified to exit 0 plainly, with --omit=optional, and with --os=linux --cpu=arm64. docs/release.md said `three platform packages` while there were already four; corrected to five along with the package count updates. Note: this has never run on real Linux aarch64 hardware. CI is the first execution. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

`ValidatePullRequests.yml` and `PRLabelChecker.yml` both filtered on `branches`, and that filter is evaluated against the pull request's own base ref. Stacked pull requests target the layer below them rather than `main`, so neither workflow fired for them: a stacked layer got only CodeQL and DCO, with no build, benchmarks, license-header, spelling or label check. That is worse than it sounds, because it defers all breakage to merge time. A layer is only built once the layer below merges and GitHub retargets it to `main`, so a stack is validated one layer at a time, in sequence, after each merge, instead of in parallel while it is being reviewed. Drop the `branches` filter from both rather than adding a pattern for stack branch names, which would only encode one contributor's naming convention. No long-lived non-`main` branches are used as pull request bases: every branch is either `release/**`, which the filter already matched, or an ordinary feature or dependabot branch, which are pull request heads rather than bases. `PRLabelChecker.yml` is widened as well because `check-labels` is a required status check on `main`. Base retargeting raises an `edited` event, which is not in that workflow's `types`, so a layer labelled while it still targeted the layer below would never run the check, and nothing would re-fire it afterwards, leaving a required check pending and blocking the merge. Check runs attach to the head SHA, so running once while the layer is stacked keeps the result valid through retargeting. Concurrency is unaffected: the group is keyed on `github.ref`, which is `refs/pull/<n>/merge` for pull request events and therefore already unique per pull request. This does mean more concurrent matrix builds when several layers are open at once, which is the intended trade for not serialising failures to merge time. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

ludfjig · 2026-09-17T19:41:18Z

+# 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.


Could you clarify why this change is needed? Upstream PR hyperlight-dev/hyperlight#1794 targets virtq-foundations and has CI runs despite retaining the branch filter. Also, checks against the old base do not validate the merge with the new base after retargeting.

The AI got confused:

Add linux-arm64 npm packaging #310 commit 252ab33 was pushed before stack #311 was registered.

Stack registration itself did not retrigger workflows, so it still showed only CodeQL and DCO.

It decided that the issue was the filters will revert this change

ludfjig · 2026-09-17T19:41:50Z

+      - 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' }}


This expression always produces --provenance because the empty string is falsy.

ludfjig · 2026-09-17T19:42:20Z

        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


Could we install and smoke-test the Linux ARM64 release tarball on an ARM64 runner before publishing? test-pack.sh only validates the x64 GNU package. The ARM64 source-build tests do not cover installation from the tarball.

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

simongdavies added this pull request to stack #311 September 16, 2026 20:37

simongdavies added the kind/enhancement New feature or improvement label Sep 16, 2026

simongdavies mentioned this pull request Sep 16, 2026

ci: run lint before build steps #313

Open

simongdavies added the ready-for-review PR is ready for (re-)review label Sep 16, 2026

ludfjig reviewed Sep 17, 2026

View reviewed changes

Revert unnecessary branch filter changes

c425ff2

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Navigation Menu

Add linux-arm64 npm packaging - #310

Add linux-arm64 npm packaging#310
simongdavies wants to merge 3 commits into
simongdavies-macos-supportfrom
simongdavies-npm-linux-arm64-packaging

simongdavies commented Sep 16, 2026 •

edited

Loading

Uh oh!

ludfjig Sep 17, 2026

Uh oh!

simongdavies Sep 21, 2026

Uh oh!

simongdavies Sep 21, 2026

Uh oh!

ludfjig Sep 17, 2026

Uh oh!

ludfjig Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

simongdavies commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this adds

Notes

Uh oh!

ludfjig Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

simongdavies Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

simongdavies Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

ludfjig Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

ludfjig Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

simongdavies commented Sep 16, 2026 •

edited

Loading