chore: update dependencies and streamline package workflows

.github/workflows/publish.yml

@@ -43,7 +43,7 @@ jobs:
       - name: Install Dependencies
         run: |
           curl -sL ${{ matrix.cmake_url }} | tar xz -C /usr/local --strip-components=1
-          npm install --ignore-scripts
+          npm ci --ignore-scripts
 
       - name: Build and Publish Bindings
         run: npm run publish:bindings -- --force
@@ -133,7 +133,7 @@ jobs:
         run: |
           curl -sL https://cmake.org/files/v3.27/cmake-3.27.9-macos-universal.tar.gz | tar xz
           echo "$(pwd)/cmake-3.27.9-macos-universal/CMake.app/Contents/bin" >> $GITHUB_PATH
-          npm install --ignore-scripts
+          npm ci --ignore-scripts
 
       - name: Build and Publish Bindings
         run: npm run publish:bindings -- --force
@@ -181,14 +181,14 @@ jobs:
           Invoke-WebRequest -Uri "https://cmake.org/files/v3.27/cmake-3.27.9-windows-x86_64.zip" -OutFile cmake.zip
           Expand-Archive cmake.zip -DestinationPath cmake
           echo "$((Resolve-Path cmake\cmake-3.27.9-windows-x86_64\bin).Path)" >> $env:GITHUB_PATH
-          npm install --ignore-scripts
+          npm ci --ignore-scripts
 
       - name: Install Dependencies (Windows arm64)
         if: runner.arch == 'ARM64'
         shell: pwsh
         run: |
           python -m pip install --upgrade pip cmake==3.30.0 ninja==1.11.1
-          npm install --ignore-scripts
+          npm ci --ignore-scripts
 
       - name: Build and Publish Bindings (Windows x64)
         if: runner.arch == 'X64'

.github/workflows/test-published.yml

@@ -45,40 +45,11 @@ jobs:
       - name: Debug Environment
         run: node -p "process.platform + ' ' + process.arch"
 
-      - name: Prepare Test Project
-        shell: pwsh
-        run: |
-          $testDir = Join-Path $env:RUNNER_TEMP "zvec-published-test"
-          Remove-Item -Recurse -Force $testDir -ErrorAction SilentlyContinue
-          New-Item -ItemType Directory -Force $testDir | Out-Null
-          Copy-Item -Recurse tests -Destination (Join-Path $testDir "tests")
-          Copy-Item jest.config.json -Destination $testDir
-          Copy-Item tsconfig.json -Destination $testDir
-          node scripts/patch-imports.js (Join-Path $testDir "tests") '@zvec/zvec'
-
-          Set-Location $testDir
-          npm init -y
-          npm install --no-package-lock --save-dev '@types/jest@^29.5.0' 'jest@^29.7.0' 'ts-jest@^29.1.2' 'typescript@^5.9.3'
-          npm install --no-package-lock '@zvec/zvec@latest'
-
-      - name: Verify Installed Version
-        shell: pwsh
-        run: |
-          Set-Location (Join-Path $env:RUNNER_TEMP "zvec-published-test")
-          npm ls '@zvec/zvec'
+      - name: Install Locked Test Tools
+        run: npm ci --ignore-scripts
 
-      - name: Smoke Test Entry Points
-        shell: pwsh
-        run: |
-          Set-Location (Join-Path $env:RUNNER_TEMP "zvec-published-test")
-          node -e "require('@zvec/zvec')"
-          node --input-type=module -e "await import('@zvec/zvec')"
-
-      - name: Run Unit Tests
-        shell: pwsh
-        run: |
-          Set-Location (Join-Path $env:RUNNER_TEMP "zvec-published-test")
-          npx jest
+      - name: Test Published Package
+        run: npm run test:package
 
   test-published-musl:
     name: Test Published (${{ matrix.name }})
@@ -88,10 +59,8 @@ jobs:
         include:
           - name: Linux x64 musl
             runner: ubuntu-24.04
-            bindings_package: "@zvec/bindings-linux-x64-musl"
           - name: Linux arm64 musl
             runner: ubuntu-24.04-arm
-            bindings_package: "@zvec/bindings-linux-arm64-musl"
     runs-on: ${{ matrix.runner }}
     env:
       MUSL_CONTAINER: zvec-node-published-musl
@@ -103,54 +72,15 @@ jobs:
       - name: Start musllinux Container
         run: |
           docker run -d --name "$MUSL_CONTAINER" \
-            -v "$GITHUB_WORKSPACE:/work:ro" \
+            -v "$GITHUB_WORKSPACE:/work" \
             -w /work \
             node:22-alpine sleep infinity
 
-      - name: Prepare Test Project
-        run: |
-          docker exec "$MUSL_CONTAINER" sh -c '
-              TEST_DIR=/tmp/zvec-published-test
-              rm -rf "$TEST_DIR"
-              mkdir -p "$TEST_DIR"
-              cp -R /work/tests "$TEST_DIR/tests"
-              cp /work/jest.config.json /work/tsconfig.json "$TEST_DIR"
-              node /work/scripts/patch-imports.js "$TEST_DIR/tests" "@zvec/zvec"
-
-              cd "$TEST_DIR"
-              npm init -y
-              npm install --no-package-lock --save-dev \
-                "@types/jest@^29.5.0" \
-                "jest@^29.7.0" \
-                "ts-jest@^29.1.2" \
-                "typescript@^5.9.3"
-              npm install --no-package-lock "@zvec/zvec@latest"
-            '
-
-      - name: Verify Installed Version
-        run: |
-          docker exec \
-            -w /tmp/zvec-published-test \
-            "$MUSL_CONTAINER" \
-            npm ls '@zvec/zvec' "${{ matrix.bindings_package }}"
+      - name: Install Locked Test Tools
+        run: docker exec "$MUSL_CONTAINER" npm ci --ignore-scripts
 
-      - name: Smoke Test Entry Points
-        run: |
-          docker exec \
-            -w /tmp/zvec-published-test \
-            "$MUSL_CONTAINER" \
-            node -e "require('@zvec/zvec')"
-          docker exec \
-            -w /tmp/zvec-published-test \
-            "$MUSL_CONTAINER" \
-            node --input-type=module -e "await import('@zvec/zvec')"
-
-      - name: Run Unit Tests
-        run: |
-          docker exec \
-            -w /tmp/zvec-published-test \
-            "$MUSL_CONTAINER" \
-            npx jest --runInBand
+      - name: Test Published Package
+        run: docker exec "$MUSL_CONTAINER" npm run test:package
 
       - name: Tear Down musllinux Container
         if: always()

.github/workflows/test-source.yml

@@ -52,7 +52,7 @@ jobs:
       - name: Install Dependencies
         run: |
           curl -sL ${{ matrix.cmake_url }} | tar xz -C /usr/local --strip-components=1
-          npm install --ignore-scripts
+          npm ci --ignore-scripts
 
       - name: Build Binaries
         run: npm run dev
@@ -90,7 +90,7 @@ jobs:
         run: |
           curl -sL https://cmake.org/files/v3.27/cmake-3.27.9-macos-universal.tar.gz | tar xz
           echo "$(pwd)/cmake-3.27.9-macos-universal/CMake.app/Contents/bin" >> $GITHUB_PATH
-          npm install --ignore-scripts
+          npm ci --ignore-scripts
 
       - name: Build Binaries
         run: npm run dev
@@ -143,14 +143,14 @@ jobs:
           Invoke-WebRequest -Uri "https://cmake.org/files/v3.27/cmake-3.27.9-windows-x86_64.zip" -OutFile cmake.zip
           Expand-Archive cmake.zip -DestinationPath cmake
           echo "$((Resolve-Path cmake\cmake-3.27.9-windows-x86_64\bin).Path)" >> $env:GITHUB_PATH
-          npm install --ignore-scripts
+          npm ci --ignore-scripts
 
       - name: Install Dependencies (Windows arm64)
         if: runner.arch == 'ARM64'
         shell: pwsh
         run: |
           python -m pip install --upgrade pip cmake==3.30.0 ninja==1.11.1
-          npm install --ignore-scripts
+          npm ci --ignore-scripts
 
       - name: Build Binaries (Windows x64)
         if: runner.arch == 'X64'

CONTRIBUTING.md

@@ -9,7 +9,7 @@ The Zvec Node.js binding is built using [node-addon-api](https://github.com/node
 - **/src/zvec/**: Contains the core [Zvec](https://github.com/alibaba/zvec) source code (included as a Git submodule).
 - **/src/binding**: Contains the binding logic.
 - **/scripts**: Contains utilities for building, packing, and publishing the project.
-- **/packages**: Holds the compiled binaries for specific platforms. Running `npm run build` generates a binary in this directory tailored to your current platform and architecture.
+- **/packages**: Contains platform package manifests and binaries staged for distribution.
 
 ## Prerequisites
 
@@ -33,7 +33,7 @@ This command will:
 
 1. Fetch necessary dependencies.
 1. Install pre-built binaries from optional dependencies based on your platform.
-1. Ensure the resulting binary is placed in the correct location for **Node.js** to load it.
+1. Run the install check to verify that the bundled binary exists or the platform package can be resolved.
 
 After installation, you can run a basic test to verify everything is working correctly:
 
@@ -122,7 +122,7 @@ npm run publish:bindings
 npm run bump:main -- <patch|minor|major>
 ```
 
-This syncs `optionalDependencies` in the root `package.json` to match the current binding versions, then bumps the main package version. Commit, tag, and push.
+This syncs `optionalDependencies` to match the current binding versions, bumps the main package version, and updates `package-lock.json`. Commit both files, tag, and push.
 
 ### 4. Publish Main Package
 

README.md

@@ -40,11 +40,11 @@ The official Node.js binding for [Zvec](https://github.com/alibaba/zvec), an ope
 npm install @zvec/zvec
 ```
 
-### ✅ Supported Platforms
+### ✅ Cross-Platform Support
 
-- Linux (x86_64, ARM64)
-- macOS (x86_64, ARM64)
-- Windows (x86_64, ARM64)
+Linux · macOS · Windows
+
+For more details, please see the [platform support documentation](https://zvec.org/en/docs/db/platforms/).
 
 ### 🛠️ Building from Source