node.yml

name: Node package

on:
  pull_request:
    branches: [main]
    paths:
      - ".github/workflows/node.yml"
      - "Cargo.lock"
      - "Cargo.toml"
      - "crates/zeppelin-embed/**"
      - "crates/zeppelin-embed-ffi/**"
      - "bindings/node/**"
      - "tests/electron-macos/**"
  push:
    branches: [main]
    paths:
      - ".github/workflows/node.yml"
      - "Cargo.lock"
      - "Cargo.toml"
      - "crates/zeppelin-embed/**"
      - "crates/zeppelin-embed-ffi/**"
      - "bindings/node/**"
      - "tests/electron-macos/**"
  workflow_dispatch:
    inputs:
      release_tag:
        description: Existing version tag to publish, for example v0.1.0
        required: true
        type: string

permissions:
  contents: read

jobs:
  package:
    name: macOS package
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.release_tag || github.ref }}
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: bindings/node/package-lock.json
      - uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: 1.93.0
          targets: aarch64-apple-darwin,x86_64-apple-darwin
      - uses: Swatinem/rust-cache@v2
      - run: npm ci
        working-directory: bindings/node
      - name: Check native source formatting
        run: xcrun clang-format --dry-run --Werror bindings/node/native/addon.cc
      - run: npm run build:native
        working-directory: bindings/node
      - run: npm test
        working-directory: bindings/node
      - run: npm run typecheck
        working-directory: bindings/node
      - name: Match a release tag to the npm version
        if: github.event_name == 'workflow_dispatch'
        env:
          RELEASE_TAG: ${{ inputs.release_tag }}
        run: test "${RELEASE_TAG#v}" = "$(node -p "require('./bindings/node/package.json').version")"
      # Both macOS slices are cross-compiled here, so each one is checked for
      # the architecture it claims as well as for carrying the engine. `file`
      # is matched on the whole expected description rather than a substring,
      # because "arm64" appears in an x86_64 build's path and would pass a
      # looser grep.
      - name: Verify each macOS addon is the right architecture and self-contained
        run: |
          set -euo pipefail
          for slice in darwin-arm64:arm64 darwin-x64:x86_64; do
            directory="${slice%%:*}"
            architecture="${slice##*:}"
            binary="bindings/node/prebuilds/$directory/zeppelin_embed.node"
            file -b "$binary" | grep -Fqx "Mach-O 64-bit bundle $architecture"
            if otool -L "$binary" | grep -q 'zeppelin_embed_ffi'; then
              echo "$binary unexpectedly depends on a separate Zeppelin FFI dylib" >&2
              exit 1
            fi
            echo "$binary: Mach-O 64-bit bundle $architecture, engine linked in"
          done
      # The x86_64 slice is cross-compiled, so building it proves nothing about
      # loading it. This runs the package's own suite against it under an
      # x86_64 Node, which is the only step that proves an Intel Mac can use
      # this package. It deliberately has no skip: a runner that cannot run
      # x86_64 fails the job rather than quietly shipping an untested binary.
      - name: Run the package suite against the x86_64 addon
        working-directory: bindings/node
        env:
          X64_NODE_VERSION: v24.21.0
        run: |
          set -euo pipefail
          workdir=$(mktemp -d)
          curl --proto '=https' --tlsv1.2 --retry 5 --location --silent --show-error --fail \
            "https://nodejs.org/dist/$X64_NODE_VERSION/node-$X64_NODE_VERSION-darwin-x64.tar.gz" \
            | tar xz -C "$workdir"
          x64node="$workdir/node-$X64_NODE_VERSION-darwin-x64/bin/node"
          test "$(arch -x86_64 "$x64node" -p 'process.arch')" = x64
          arch -x86_64 "$x64node" --test test/*.test.mjs
      - name: Pack and smoke-test the installed artifact
        id: pack
        working-directory: bindings/node
        run: |
          set -euo pipefail
          tarball=$(npm pack --json | node -e 'let value=""; process.stdin.on("data", chunk => value += chunk); process.stdin.on("end", () => console.log(JSON.parse(value)[0].filename));')
          consumer=$(mktemp -d)
          cp test/installed-package-smoke.cjs "$consumer/smoke.cjs"
          cp test/installed-package-type-smoke.ts "$consumer/type-smoke.ts"
          cd "$consumer"
          npm init --yes >/dev/null
          npm install "$GITHUB_WORKSPACE/bindings/node/$tarball"
          node smoke.cjs
          "$GITHUB_WORKSPACE/bindings/node/node_modules/.bin/tsc" \
            --module node16 --moduleResolution node16 --target es2022 \
            --strict --noEmit type-smoke.ts
          printf 'tarball=%s\n' "$tarball" >> "$GITHUB_OUTPUT"
      # The prebuilt binaries, not the tarball. A Mac cannot build the Windows
      # addon, so the tarball this job packs is a smoke-test artefact only;
      # `assemble` is what combines both platforms' prebuilds into the single
      # tarball a release publishes. Both macOS slices travel as one artefact
      # because one job builds both.
      - uses: actions/upload-artifact@v4
        with:
          name: prebuilds-darwin
          path: bindings/node/prebuilds
          if-no-files-found: error

  windows-package:
    name: Windows x64 package
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.release_tag || github.ref }}
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: bindings/node/package-lock.json
      - uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: 1.93.0
          targets: x86_64-pc-windows-msvc
      - uses: Swatinem/rust-cache@v2
      - run: npm ci
        working-directory: bindings/node
      # Both variants. The Electron arm downloads Electron's headers, so it is
      # built only when ZE_ELECTRON_VERSION asks for it, and the loader accepts
      # only the majors this package actually ships.
      - run: npm run build:native
        working-directory: bindings/node
        env:
          ZE_ELECTRON_VERSION: 44.4.1
      - run: npm test
        working-directory: bindings/node
      - run: npm run typecheck
        working-directory: bindings/node
      - run: npm run check:prebuilt
        working-directory: bindings/node
      # Packs, installs into a consumer created outside the repository, runs
      # the runtime smoke there and type-checks against the installed
      # declarations. A consumer outside the build tree cannot resolve a
      # Zeppelin DLL out of `target`, so this also proves the addon carries the
      # engine inside it, which is what `otool` checks on the macOS side.
      - run: npm run smoke:install
        working-directory: bindings/node
      - uses: actions/upload-artifact@v4
        with:
          name: prebuild-win32-x64
          path: bindings/node/prebuilds/win32-x64
          if-no-files-found: error

  electron-package:
    name: Signed Electron lifecycle (${{ matrix.arch }})
    needs: package
    runs-on: macos-14
    timeout-minutes: 35
    strategy:
      fail-fast: false
      matrix:
        arch: [arm64, x64]
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.release_tag || github.ref }}
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: tests/electron-macos/package-lock.json
      - uses: actions/download-artifact@v4
        with:
          name: prebuilds-darwin
          path: bindings/node/prebuilds
      - run: npm ci --ignore-scripts --no-audit --no-fund
        working-directory: tests/electron-macos
      - name: Package, sign, verify, and run Electron
        run: npm run smoke -- ${{ matrix.arch }} single
        working-directory: tests/electron-macos
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: electron-package-${{ matrix.arch }}
          path: tests/electron-macos/evidence
          if-no-files-found: error

  electron-isolation:
    name: Electron and Node isolation (${{ matrix.arch }})
    needs: package
    runs-on: macos-14
    timeout-minutes: 35
    strategy:
      fail-fast: false
      matrix:
        arch: [arm64, x64]
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.release_tag || github.ref }}
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: tests/electron-macos/package-lock.json
      - uses: actions/download-artifact@v4
        with:
          name: prebuilds-darwin
          path: bindings/node/prebuilds
      - name: Prove native reload, worker loading, and finalization in Node
        run: node --test bindings/node/test/double-load.test.mjs
      - run: npm ci --ignore-scripts --no-audit --no-fund
        working-directory: tests/electron-macos
      - name: Package, sign, verify, and run Electron
        run: npm run smoke -- ${{ matrix.arch }} concurrent
        working-directory: tests/electron-macos
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: electron-isolation-${{ matrix.arch }}
          path: tests/electron-macos/evidence
          if-no-files-found: error

  assemble:
    name: Assemble the release tarball
    needs: [package, windows-package]
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.release_tag || github.ref }}
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - uses: actions/download-artifact@v4
        with:
          name: prebuilds-darwin
          path: bindings/node/prebuilds
      - uses: actions/download-artifact@v4
        with:
          name: prebuild-win32-x64
          path: bindings/node/prebuilds/win32-x64
      - name: Pack every platform into one tarball
        id: pack
        working-directory: bindings/node
        run: |
          set -euo pipefail
          tarball=$(npm pack --json | node -e 'let value=""; process.stdin.on("data", chunk => value += chunk); process.stdin.on("end", () => console.log(JSON.parse(value)[0].filename));')
          printf 'tarball=%s\n' "$tarball" >> "$GITHUB_OUTPUT"
      # `npm pack` silently omits `files` entries that are absent, so a tarball
      # can advertise a platform and ship nothing for it; npm would install it
      # there and the failure would surface at require time. This is the gate
      # that refuses that tarball, and it reads the binary list from
      # `package.json` so adding a platform cannot escape it.
      - name: Verify the tarball contains every advertised binary
        working-directory: bindings/node
        run: npm run verify:release -- "${{ steps.pack.outputs.tarball }}"
      - uses: actions/upload-artifact@v4
        with:
          name: zeppelin-embed-node-package
          path: bindings/node/${{ steps.pack.outputs.tarball }}
          if-no-files-found: error

  publish:
    name: Publish npm package
    if: github.event_name == 'workflow_dispatch'
    needs: [assemble, electron-package, electron-isolation]
    runs-on: macos-14
    environment: npm
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: zeppelin-embed-node-package
          path: package
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org
          package-manager-cache: false
      - run: npm install --global npm@11
      - run: npm publish ./package/*.tgz --access public --provenance
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}