Review Feedabck

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

Author: simongdavies

.github/workflows/npm-publish.yml

@@ -33,6 +33,10 @@ permissions:
   contents: read
   id-token: write
 
+concurrency:
+  group: npm-publish-${{ inputs.version }}
+  cancel-in-progress: false
+
 env:
   WORKING_DIR: src/js-host-api
 
@@ -45,6 +49,9 @@ jobs:
           - target: x86_64-unknown-linux-gnu
             os: [self-hosted, Linux, X64, "1ES.Pool=hld-kvm-amd"]
             build_name: linux-x64-gnu
+          - target: x86_64-unknown-linux-musl
+            os: [self-hosted, Linux, X64, "1ES.Pool=hld-kvm-amd"]
+            build_name: linux-x64-musl
           - target: x86_64-pc-windows-msvc
             os: [self-hosted, Windows, X64, "1ES.Pool=hld-win2022-amd"]
             build_name: win32-x64-msvc
@@ -54,6 +61,11 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Validate version format
+        run: node -e "if (!/^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/.test(process.env.VERSION)) { console.error('Invalid version:', process.env.VERSION); process.exit(1); }"
+        env:
+          VERSION: ${{ inputs.version }}
+
       - name: Hyperlight setup
         uses: hyperlight-dev/ci-setup-workflow@v1.8.0
         with:
@@ -72,13 +84,19 @@ jobs:
 
       - name: Set package version
         working-directory: ${{ env.WORKING_DIR }}
-        shell: bash
-        run: |
-          npm version ${{ inputs.version }} --no-git-tag-version --allow-same-version
+        run: npm version ${{ inputs.version }} --no-git-tag-version --allow-same-version
+
+      - name: Install musl tools
+        if: contains(matrix.target, 'musl')
+        run: sudo apt-get update && sudo apt-get install -y musl-tools
+
+      - name: Add musl Rust target
+        if: contains(matrix.target, 'musl')
+        run: rustup target add x86_64-unknown-linux-musl
 
       - name: Build native module
         working-directory: ${{ env.WORKING_DIR }}
-        run: npm run build
+        run: npm run build -- --target ${{ matrix.target }}
 
       - name: Upload artifact
         uses: actions/upload-artifact@v8
@@ -93,6 +111,11 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - name: Validate version format
+        run: node -e "if (!/^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/.test(process.env.VERSION)) { console.error('Invalid version:', process.env.VERSION); process.exit(1); }"
+        env:
+          VERSION: ${{ inputs.version }}
+
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
@@ -105,12 +128,18 @@ jobs:
         working-directory: ${{ env.WORKING_DIR }}
         run: npm ci --ignore-scripts --omit=optional
 
-      - name: Download Linux artifact
+      - name: Download Linux GNU artifact
         uses: actions/download-artifact@v8
         with:
           name: bindings-linux-x64-gnu
           path: ${{ env.WORKING_DIR }}/artifacts/linux-x64-gnu
 
+      - name: Download Linux musl artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: bindings-linux-x64-musl
+          path: ${{ env.WORKING_DIR }}/artifacts/linux-x64-musl
+
       - name: Download Windows artifact
         uses: actions/download-artifact@v8
         with:
@@ -125,19 +154,24 @@ jobs:
         run: |
           # Rename artifacts to match napi-rs naming convention
           mv artifacts/linux-x64-gnu/*.node npm/linux-x64-gnu/js-host-api.linux-x64-gnu.node
+          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
           ls -la npm/linux-x64-gnu/
+          ls -la npm/linux-x64-musl/
           ls -la npm/win32-x64-msvc/
 
       - name: Set package versions
         working-directory: ${{ env.WORKING_DIR }}
         run: |
           # Update main package version
-          npm version ${{ inputs.version }} --no-git-tag-version --allow-same-version
+          npm version "$VERSION" --no-git-tag-version --allow-same-version
           
           # Update platform package versions
-          cd npm/linux-x64-gnu && npm version ${{ inputs.version }} --no-git-tag-version --allow-same-version
-          cd ../win32-x64-msvc && npm version ${{ inputs.version }} --no-git-tag-version --allow-same-version
+          cd npm/linux-x64-gnu && npm version "$VERSION" --no-git-tag-version --allow-same-version
+          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
+        env:
+          VERSION: ${{ inputs.version }}
 
       - name: Update optionalDependencies versions
         working-directory: ${{ env.WORKING_DIR }}
@@ -148,12 +182,14 @@ jobs:
             const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
             for (const dep of Object.keys(pkg.optionalDependencies || {})) {
               if (dep.startsWith('@hyperlight/js-host-api-')) {
-                pkg.optionalDependencies[dep] = '${{ inputs.version }}';
+                pkg.optionalDependencies[dep] = process.env.VERSION;
               }
             }
             fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
           "
           cat package.json
+        env:
+          VERSION: ${{ inputs.version }}
 
       - name: Generate JS bindings (index.js and index.d.ts)
         working-directory: ${{ env.WORKING_DIR }}
@@ -162,36 +198,46 @@ jobs:
           npx napi prepublish -t npm --skip-gh-release
           ls -la index.js index.d.ts
 
-      - name: Publish Linux package
-        if: ${{ !inputs.dry-run }}
+      - name: Publish Linux GNU package
+        if: ${{ !inputs['dry-run'] }}
         working-directory: ${{ env.WORKING_DIR }}/npm/linux-x64-gnu
         run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+      - name: Publish Linux musl package
+        if: ${{ !inputs['dry-run'] }}
+        working-directory: ${{ env.WORKING_DIR }}/npm/linux-x64-musl
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
       - name: Publish Windows package
-        if: ${{ !inputs.dry-run }}
+        if: ${{ !inputs['dry-run'] }}
         working-directory: ${{ env.WORKING_DIR }}/npm/win32-x64-msvc
         run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Publish main package
-        if: ${{ !inputs.dry-run }}
+        if: ${{ !inputs['dry-run'] }}
         working-directory: ${{ env.WORKING_DIR }}
         run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Dry run - show what would be published
-        if: ${{ inputs.dry-run }}
+        if: ${{ inputs['dry-run'] }}
         working-directory: ${{ env.WORKING_DIR }}
         run: |
           echo "=== DRY RUN - Would publish the following packages ==="
           echo ""
           echo "--- @hyperlight/js-host-api-linux-x64-gnu ---"
           npm pack ./npm/linux-x64-gnu --dry-run
           echo ""
+          echo "--- @hyperlight/js-host-api-linux-x64-musl ---"
+          npm pack ./npm/linux-x64-musl --dry-run
+          echo ""
           echo "--- @hyperlight/js-host-api-win32-x64-msvc ---"
           npm pack ./npm/win32-x64-msvc --dry-run
           echo ""

src/js-host-api/.npmignore

@@ -30,3 +30,6 @@ test-examples.sh
 
 # Exclude artifacts directory (only used during CI)
 artifacts/
+
+# Exclude platform sub-packages (published separately as optionalDependencies)
+npm/

src/js-host-api/README.md

@@ -634,10 +634,19 @@ To create an npm token:
 
 ### Package Structure
 
-The npm release consists of three packages:
+The npm release consists of the following packages:
 
 | Package | Description |
 |---------|-------------|
 | `@hyperlight/js-host-api` | Main package (installs correct binary automatically) |
-| `@hyperlight/js-host-api-linux-x64-gnu` | Linux x86_64 native binary |
+| `@hyperlight/js-host-api-linux-x64-gnu` | Linux x86_64 (glibc) native binary |
+| `@hyperlight/js-host-api-linux-x64-musl` | Linux x86_64 (musl/Alpine) native binary |
 | `@hyperlight/js-host-api-win32-x64-msvc` | Windows x86_64 native binary |
+
+### How Platform Selection Works
+
+This project uses the [napi-rs](https://napi.rs/docs/deep-dive/release#3-the-native-addon-for-different-platforms-is-distributed-through-different-npm-packages) approach for distributing native addons across platforms. Each platform-specific binary is published as a separate npm package and listed as an `optionalDependency` of the main package.
+
+**At install time:** npm uses the `os`, `cpu`, and `libc` fields in each platform sub-package's `package.json` to determine which optional dependency to install. Packages that don't match the user's platform are silently skipped. The main package itself does **not** have `os`/`cpu` fields because it contains only JavaScript — restricting it would prevent installation on unsupported platforms even for type-checking or development purposes.
+
+**At runtime:** The napi-rs generated `index.js` detects the platform (including glibc vs musl on Linux) and loads the correct `.node` binary.

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

@@ -23,5 +23,8 @@
   },
   "engines": {
     "node": ">= 18"
-  }
+  },
+  "libc": [
+    "glibc"
+  ]
 }

src/js-host-api/npm/linux-x64-musl/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hyperlight/js-host-api-linux-x64-musl",
+  "version": "0.17.0",
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "js-host-api.linux-x64-musl.node",
+  "files": [
+    "js-host-api.linux-x64-musl.node"
+  ],
+  "description": "Node.js API bindings for Hyperlight JS - Linux x64 musl",
+  "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": [
+    "musl"
+  ]
+}

src/js-host-api/package-lock.json

@@ -16,12 +16,14 @@
     "binaryName": "js-host-api",
     "targets": [
       "x86_64-unknown-linux-gnu",
+      "x86_64-unknown-linux-musl",
       "x86_64-pc-windows-msvc"
     ]
   },
   "license": "Apache-2.0",
   "optionalDependencies": {
     "@hyperlight/js-host-api-linux-x64-gnu": "0.17.0",
+    "@hyperlight/js-host-api-linux-x64-musl": "0.17.0",
     "@hyperlight/js-host-api-win32-x64-msvc": "0.17.0"
   },
   "devDependencies": {