release-node.yml

name: Release Node package group (npm)

on:
  workflow_dispatch:
    inputs:
      release_tag:
        description: "Version label to publish, for example v0.8.0-alpha.5"
        required: true
        type: string
      source_ref:
        description: "Reviewed full commit SHA or matching release tag; main is build-only"
        required: true
        default: "main"
        type: string
      recovery_run_id:
        description: "Prior non-publishing release-node run containing the verified package group"
        required: false
        default: ""
        type: string
      publish_to_npm:
        description: "Publish the verified @mermanjs/node package group"
        required: true
        default: false
        type: boolean

permissions:
  contents: read

env:
  CARGO_TERM_COLOR: always

jobs:
  validate-inputs:
    name: validate-inputs
    runs-on: ubuntu-24.04
    outputs:
      source_sha: ${{ steps.source.outputs.source_sha }}
      source_tree: ${{ steps.source.outputs.source_tree }}
      source_ref: ${{ steps.release.outputs.source_ref }}
      release_tag: ${{ steps.release.outputs.release_tag }}
      version: ${{ steps.release.outputs.version }}
      npm_dist_tag: ${{ steps.release.outputs.npm_dist_tag }}
      recovery_run_id: ${{ steps.release.outputs.recovery_run_id }}
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          ref: ${{ github.workflow_sha }}
          persist-credentials: false

      - name: Validate release input
        id: release
        shell: bash
        env:
          DISPATCH_RELEASE_TAG: ${{ inputs.release_tag }}
          DISPATCH_SOURCE_REF: ${{ inputs.source_ref }}
          DISPATCH_RECOVERY_RUN_ID: ${{ inputs.recovery_run_id }}
          DISPATCH_PUBLISH_TO_NPM: ${{ inputs.publish_to_npm }}
        run: |
          set -euo pipefail
          RELEASE_TAG="$DISPATCH_RELEASE_TAG"
          SOURCE_REF="$DISPATCH_SOURCE_REF"
          version="$(python3 scripts/release-version.py canonical --version "$RELEASE_TAG")"
          test "$RELEASE_TAG" = "v$version"
          npm_dist_tag="$(python3 scripts/release-version.py npm-dist-tag --version "$RELEASE_TAG")"

          test -n "$SOURCE_REF"
          [[ "$SOURCE_REF" != *$'\n'* && "$SOURCE_REF" != *$'\r'* ]] || {
            echo "::error::source_ref must be a single line" >&2
            exit 1
          }
          RECOVERY_RUN_ID="$DISPATCH_RECOVERY_RUN_ID"
          if [ -n "$RECOVERY_RUN_ID" ]; then
            [[ "$RECOVERY_RUN_ID" =~ ^[1-9][0-9]*$ ]] || {
              echo "::error::recovery_run_id must be a positive GitHub Actions run id" >&2
              exit 1
            }
            [[ "$DISPATCH_PUBLISH_TO_NPM" == "true" ]] || {
              echo "::error::recovery_run_id requires publish_to_npm=true" >&2
              exit 1
            }
          fi
          if [[ "$SOURCE_REF" =~ ^[0-9a-f]{40}$ ]]; then
            validated_source_ref="$SOURCE_REF"
          elif [[ "$SOURCE_REF" == "main" || "$SOURCE_REF" == "refs/heads/main" ]]; then
            if [[ "$DISPATCH_PUBLISH_TO_NPM" == "true" ]]; then
              echo "::error::main is allowed only for a non-publishing build; use a reviewed full commit SHA or matching release tag to publish." >&2
              exit 1
            fi
            validated_source_ref="$SOURCE_REF"
          elif [[ "$SOURCE_REF" == "$RELEASE_TAG" || "$SOURCE_REF" == "refs/tags/$RELEASE_TAG" ]]; then
            validated_source_ref="refs/tags/$RELEASE_TAG"
          else
            echo "::error::source_ref tag must match release_tag; use a reviewed full commit SHA, a matching release tag, or main only for a non-publishing build." >&2
            exit 1
          fi
          {
            printf 'source_ref=%s\n' "$validated_source_ref"
            printf 'release_tag=%s\n' "$RELEASE_TAG"
            printf 'version=%s\n' "$version"
            printf 'npm_dist_tag=%s\n' "$npm_dist_tag"
            printf 'recovery_run_id=%s\n' "$RECOVERY_RUN_ID"
          } >> "$GITHUB_OUTPUT"

      - uses: actions/checkout@v7.0.1
        with:
          ref: ${{ steps.release.outputs.source_ref }}
          path: release-source
          fetch-depth: 1
          persist-credentials: false

      - name: Resolve immutable release source
        id: source
        shell: bash
        env:
          EXPECTED_SOURCE_REF: ${{ steps.release.outputs.source_ref }}
        run: |
          set -euo pipefail
          source_sha="$(git -C release-source rev-parse 'HEAD^{commit}')"
          source_tree="$(git -C release-source rev-parse 'HEAD^{tree}')"
          if [[ "$EXPECTED_SOURCE_REF" =~ ^[0-9a-f]{40}$ ]]; then
            test "$source_sha" = "$EXPECTED_SOURCE_REF"
          fi
          {
            printf 'source_sha=%s\n' "$source_sha"
            printf 'source_tree=%s\n' "$source_tree"
          } >> "$GITHUB_OUTPUT"

  loader:
    needs: validate-inputs
    name: loader package
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          ref: ${{ needs.validate-inputs.outputs.source_sha }}
          persist-credentials: false

      - name: Verify pinned release source and versions
        env:
          SOURCE_SHA: ${{ needs.validate-inputs.outputs.source_sha }}
          SOURCE_TREE: ${{ needs.validate-inputs.outputs.source_tree }}
          VERSION: ${{ needs.validate-inputs.outputs.version }}
        run: |
          set -euo pipefail
          test "$(git rev-parse 'HEAD^{commit}')" = "$SOURCE_SHA"
          test "$(git rev-parse 'HEAD^{tree}')" = "$SOURCE_TREE"
          python3 scripts/release-version.py check --version "$VERSION"
          python3 scripts/sync-release-legal-materials.py --check

      - name: Setup Node
        uses: actions/setup-node@v7.0.0
        with:
          node-version: "24"
          cache: npm
          cache-dependency-path: platforms/node/package-lock.json

      - name: Verify Node package contracts
        run: |
          npm ci --prefix platforms/node
          npm test --prefix platforms/node
          node platforms/node/scripts/verify-packages.mjs

      - name: Pack loader package
        shell: bash
        run: |
          set -euo pipefail
          package_root="$RUNNER_TEMP/node-loader-package"
          artifact_dir="$RUNNER_TEMP/node-loader-artifact"
          node platforms/node/scripts/assemble-packages.mjs \
            --loader-only \
            --output-root "$package_root"
          mkdir -p "$artifact_dir"
          npm pack "$package_root/node" \
            --json \
            --pack-destination "$artifact_dir" > "$RUNNER_TEMP/node-loader-pack.json"
          test "$(find "$artifact_dir" -maxdepth 1 -name '*.tgz' -type f | wc -l | tr -d ' ')" = 1

      - name: Upload loader package
        uses: actions/upload-artifact@v7.0.1
        with:
          name: merman-node-npm-loader
          path: ${{ runner.temp }}/node-loader-artifact/*.tgz
          if-no-files-found: error

  node-wasm-package:
    needs: validate-inputs
    name: Node WASM package
    runs-on: ubuntu-24.04
    defaults:
      run:
        shell: bash
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          ref: ${{ needs.validate-inputs.outputs.source_sha }}
          persist-credentials: false

      - name: Verify pinned release source and versions
        env:
          SOURCE_SHA: ${{ needs.validate-inputs.outputs.source_sha }}
          SOURCE_TREE: ${{ needs.validate-inputs.outputs.source_tree }}
          VERSION: ${{ needs.validate-inputs.outputs.version }}
        run: |
          set -euo pipefail
          test "$(git rev-parse 'HEAD^{commit}')" = "$SOURCE_SHA"
          test "$(git rev-parse 'HEAD^{tree}')" = "$SOURCE_TREE"
          python3 scripts/release-version.py check --version "$VERSION"

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@1.95.0
        with:
          targets: wasm32-unknown-unknown

      - name: Rust cache
        uses: Swatinem/rust-cache@v2.9.2
        with:
          workspaces: crates/merman-node

      - name: Setup Node
        uses: actions/setup-node@v7.0.0
        with:
          node-version: "24"
          cache: npm
          cache-dependency-path: platforms/node/package-lock.json

      - name: Install pinned Node build dependencies
        run: npm ci --prefix platforms/node

      - name: Install wasm-pack
        run: cargo install wasm-pack --version 0.15.0 --locked

      - name: Build and probe Node WASM candidate
        run: node platforms/node/scripts/build-candidate.mjs --candidate node-wasm

      - name: Assemble and verify Node WASM package
        env:
          VERSION: ${{ needs.validate-inputs.outputs.version }}
        run: |
          set -euo pipefail
          package_root="$RUNNER_TEMP/node-wasm-package"
          artifact_dir="$RUNNER_TEMP/node-wasm-artifact"
          node platforms/node/scripts/assemble-packages.mjs --wasm --output-root "$package_root"
          node platforms/node/scripts/verify-packages.mjs --packed-root "$package_root"
          mkdir -p "$artifact_dir"
          npm pack "$package_root/node-wasm" --json --pack-destination "$artifact_dir" > "$RUNNER_TEMP/node-wasm-pack.json"

          smoke_root="$RUNNER_TEMP/node-wasm-install-smoke"
          mkdir -p "$smoke_root"
          cd "$smoke_root"
          npm init -y >/dev/null
          npm install --ignore-scripts --no-audit --no-fund "$artifact_dir"/*.tgz >/dev/null
          node "$GITHUB_WORKSPACE/platforms/node/scripts/smoke-installed-package.mjs" \
            --project "$smoke_root" \
            --version "$VERSION" \
            --target node-wasm

      - name: Upload Node WASM package
        uses: actions/upload-artifact@v7.0.1
        with:
          name: merman-node-npm-wasm
          path: ${{ runner.temp }}/node-wasm-artifact/*.tgz
          if-no-files-found: error

  platform:
    needs: validate-inputs
    name: platform (${{ matrix.target }})
    runs-on: ${{ matrix.runner }}
    defaults:
      run:
        shell: bash
    strategy:
      fail-fast: false
      matrix:
        include:
          - target: darwin-arm64
            runner: macos-15
            rust_target: aarch64-apple-darwin
          - target: darwin-x64
            runner: macos-15-intel
            rust_target: x86_64-apple-darwin
          - target: linux-x64-gnu
            runner: ubuntu-24.04
            rust_target: x86_64-unknown-linux-gnu
          - target: linux-x64-musl
            runner: ubuntu-24.04
            rust_target: x86_64-unknown-linux-musl
          - target: win32-x64-msvc
            runner: windows-2025-vs2026
            rust_target: x86_64-pc-windows-msvc
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          ref: ${{ needs.validate-inputs.outputs.source_sha }}
          persist-credentials: false

      - name: Verify pinned release source and versions
        env:
          SOURCE_SHA: ${{ needs.validate-inputs.outputs.source_sha }}
          SOURCE_TREE: ${{ needs.validate-inputs.outputs.source_tree }}
          VERSION: ${{ needs.validate-inputs.outputs.version }}
        run: |
          set -euo pipefail
          test "$(git rev-parse 'HEAD^{commit}')" = "$SOURCE_SHA"
          test "$(git rev-parse 'HEAD^{tree}')" = "$SOURCE_TREE"
          python3 scripts/release-version.py check --version "$VERSION"

      - name: Install Rust toolchain
        if: matrix.target != 'linux-x64-musl' && matrix.target != 'linux-x64-gnu'
        uses: dtolnay/rust-toolchain@1.95.0
        with:
          targets: ${{ matrix.rust_target }}

      - name: Rust cache
        if: matrix.target != 'linux-x64-musl' && matrix.target != 'linux-x64-gnu'
        uses: Swatinem/rust-cache@v2.9.2
        with:
          workspaces: crates/merman-node

      - name: Build, package, and smoke musl target
        if: matrix.target == 'linux-x64-musl'
        env:
          TARGET: ${{ matrix.target }}
          VERSION: ${{ needs.validate-inputs.outputs.version }}
        run: |
          set -euo pipefail
          docker build \
            --platform linux/amd64 \
            --file platforms/node/Dockerfile.musl \
            --build-arg NODE_IMAGE=node:24-alpine3.22 \
            --build-arg RUST_IMAGE=rust:1.95-alpine3.22 \
            --tag merman-node-musl:ci \
            platforms/node
          docker run --rm \
            --platform linux/amd64 \
            -e CARGO_INCREMENTAL=0 \
            -e TARGET="$TARGET" \
            -e VERSION="$VERSION" \
            -v "$GITHUB_WORKSPACE:/work" \
            -v "$RUNNER_TEMP:/runner-temp" \
            -w /work \
            merman-node-musl:ci \
            sh -c '
              set -eu
              git config --global --add safe.directory /work
              npm ci --prefix platforms/node
              node platforms/node/scripts/build-candidate.mjs --candidate napi --target "$TARGET"
              package_root=/runner-temp/node-packages
              artifact_dir=/runner-temp/node-platform-artifact
              smoke_tarballs=/runner-temp/node-smoke-tarballs
              smoke_root=/runner-temp/node-install-smoke
              node platforms/node/scripts/assemble-packages.mjs --target "$TARGET" --output-root "$package_root"
              node platforms/node/scripts/verify-packages.mjs --packed-root "$package_root"
              mkdir -p "$artifact_dir" "$smoke_tarballs" "$smoke_root"
              npm pack "$package_root/node" --json --pack-destination "$smoke_tarballs" >/runner-temp/node-root-pack.json
              npm pack "$package_root/$TARGET" --json --pack-destination "$artifact_dir" >/runner-temp/node-target-pack.json
              cp "$artifact_dir"/*.tgz "$smoke_tarballs"/
              test "$(find "$artifact_dir" -maxdepth 1 -name "*.tgz" -type f | wc -l | tr -d " ")" = 1
              cd "$smoke_root"
              npm init -y >/dev/null
              npm install --ignore-scripts --no-audit --no-fund "$smoke_tarballs"/*.tgz >/dev/null
              node /work/platforms/node/scripts/smoke-installed-package.mjs --project "$smoke_root" --version "$VERSION" --target "$TARGET"
            '

      - name: Build, package, and smoke GNU target
        if: matrix.target == 'linux-x64-gnu'
        env:
          TARGET: ${{ matrix.target }}
          VERSION: ${{ needs.validate-inputs.outputs.version }}
        run: |
          set -euo pipefail
          docker build \
            --platform linux/amd64 \
            --file platforms/node/Dockerfile.gnu \
            --build-arg NODE_IMAGE=node:24-bullseye \
            --build-arg RUST_IMAGE=rust:1.95-bullseye \
            --tag merman-node-gnu:ci \
            platforms/node
          docker run --rm \
            --platform linux/amd64 \
            -e CARGO_INCREMENTAL=0 \
            -e TARGET="$TARGET" \
            -e VERSION="$VERSION" \
            -v "$GITHUB_WORKSPACE:/work" \
            -v "$RUNNER_TEMP:/runner-temp" \
            -w /work \
            merman-node-gnu:ci \
            sh -c '
              set -eu
              git config --global --add safe.directory /work
              test "$(node -p "process.report.getReport().header.glibcVersionRuntime")" = "2.31"
              npm ci --prefix platforms/node
              node platforms/node/scripts/build-candidate.mjs --candidate napi --target "$TARGET"
              package_root=/runner-temp/node-packages
              artifact_dir=/runner-temp/node-platform-artifact
              smoke_tarballs=/runner-temp/node-smoke-tarballs
              smoke_root=/runner-temp/node-install-smoke
              node platforms/node/scripts/assemble-packages.mjs --target "$TARGET" --output-root "$package_root"
              node platforms/node/scripts/verify-packages.mjs --packed-root "$package_root"
              mkdir -p "$artifact_dir" "$smoke_tarballs" "$smoke_root"
              npm pack "$package_root/node" --json --pack-destination "$smoke_tarballs" >/runner-temp/node-root-pack.json
              npm pack "$package_root/$TARGET" --json --pack-destination "$artifact_dir" >/runner-temp/node-target-pack.json
              cp "$artifact_dir"/*.tgz "$smoke_tarballs"/
              cd "$smoke_root"
              npm init -y >/dev/null
              npm install --ignore-scripts --no-audit --no-fund "$smoke_tarballs"/*.tgz >/dev/null
              node /work/platforms/node/scripts/smoke-installed-package.mjs --project "$smoke_root" --version "$VERSION" --target "$TARGET"
            '

      - name: Setup Node
        if: matrix.target != 'linux-x64-musl' && matrix.target != 'linux-x64-gnu'
        uses: actions/setup-node@v7.0.0
        with:
          node-version: "24"
          cache: npm
          cache-dependency-path: platforms/node/package-lock.json

      - name: Install pinned Node build dependencies
        if: matrix.target != 'linux-x64-musl' && matrix.target != 'linux-x64-gnu'
        run: npm ci --prefix platforms/node

      - name: Build and probe native package
        if: matrix.target != 'linux-x64-musl' && matrix.target != 'linux-x64-gnu'
        run: node platforms/node/scripts/build-candidate.mjs --candidate napi --target "${{ matrix.target }}"

      - name: Assemble and verify target package
        if: matrix.target != 'linux-x64-musl' && matrix.target != 'linux-x64-gnu'
        env:
          TARGET: ${{ matrix.target }}
        run: |
          set -euo pipefail
          package_root="$RUNNER_TEMP/node-packages"
          node platforms/node/scripts/assemble-packages.mjs \
            --target "$TARGET" \
            --output-root "$package_root"
          node platforms/node/scripts/verify-packages.mjs --packed-root "$package_root"

      - name: Pack and install-smoke target package
        if: matrix.target != 'linux-x64-musl' && matrix.target != 'linux-x64-gnu'
        env:
          TARGET: ${{ matrix.target }}
          VERSION: ${{ needs.validate-inputs.outputs.version }}
        run: |
          set -euo pipefail
          package_root="$RUNNER_TEMP/node-packages"
          artifact_dir="$RUNNER_TEMP/node-platform-artifact"
          smoke_tarballs="$RUNNER_TEMP/node-smoke-tarballs"
          mkdir -p "$artifact_dir" "$smoke_tarballs"
          npm pack "$package_root/node" --json --pack-destination "$smoke_tarballs" > "$RUNNER_TEMP/node-root-pack.json"
          npm pack "$package_root/$TARGET" --json --pack-destination "$artifact_dir" > "$RUNNER_TEMP/node-target-pack.json"
          cp "$artifact_dir"/*.tgz "$smoke_tarballs/"
          test "$(find "$artifact_dir" -maxdepth 1 -name '*.tgz' -type f | wc -l | tr -d ' ')" = 1

          smoke_root="$RUNNER_TEMP/node-install-smoke"
          mkdir -p "$smoke_root"
          cd "$smoke_root"
          npm init -y >/dev/null
          npm install --ignore-scripts --no-audit --no-fund "$smoke_tarballs"/*.tgz >/dev/null
          node "$GITHUB_WORKSPACE/platforms/node/scripts/smoke-installed-package.mjs" \
            --project "$smoke_root" \
            --version "$VERSION" \
            --target "$TARGET"

      - name: Upload target package
        uses: actions/upload-artifact@v7.0.1
        with:
          name: merman-node-npm-${{ matrix.target }}
          path: ${{ runner.temp }}/node-platform-artifact/*.tgz
          if-no-files-found: error

  package-group:
    needs:
      - validate-inputs
      - loader
      - node-wasm-package
      - platform
    name: verified package group
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          ref: ${{ needs.validate-inputs.outputs.source_sha }}
          persist-credentials: false

      - name: Download all Node npm packages
        uses: actions/download-artifact@v8.0.1
        with:
          pattern: merman-node-npm-*
          path: target/node-npm-package-group
          merge-multiple: true

      - name: Create and verify Node package group manifest
        env:
          VERSION: ${{ needs.validate-inputs.outputs.version }}
          SOURCE_SHA: ${{ needs.validate-inputs.outputs.source_sha }}
          NPM_DIST_TAG: ${{ needs.validate-inputs.outputs.npm_dist_tag }}
        run: |
          set -euo pipefail
          python3 scripts/node_package_group.py create-manifest \
            --artifact-dir target/node-npm-package-group \
            --descriptor platforms/node/package-surfaces.json \
            --version "$VERSION" \
            --source-sha "$SOURCE_SHA" \
            --target-dist-tag "$NPM_DIST_TAG"
          python3 scripts/node_package_group.py verify-artifact \
            --manifest target/node-npm-package-group/node-package-group.json \
            --artifact-dir target/node-npm-package-group \
            --descriptor platforms/node/package-surfaces.json \
            --version "$VERSION" \
            --source-sha "$SOURCE_SHA" \
            --target-dist-tag "$NPM_DIST_TAG"

      - name: Upload verified Node package group
        uses: actions/upload-artifact@v7.0.1
        with:
          name: merman-node-npm-package-group
          path: target/node-npm-package-group
          if-no-files-found: error

  publish:
    needs:
      - validate-inputs
      - package-group
    if: ${{ always() && needs.validate-inputs.result == 'success' && inputs.publish_to_npm && (needs.package-group.result == 'success' || needs.validate-inputs.outputs.recovery_run_id != '') }}
    name: publish npm package group
    runs-on: ubuntu-24.04
    environment: npm
    permissions:
      actions: read
      contents: read
      id-token: write
    steps:
      - name: Checkout trusted release verifier
        uses: actions/checkout@v7.0.1
        with:
          ref: ${{ github.workflow_sha }}
          path: trusted
          persist-credentials: false

      - name: Checkout immutable package descriptor
        uses: actions/checkout@v7.0.1
        with:
          ref: ${{ needs.validate-inputs.outputs.source_sha }}
          path: release-source
          persist-credentials: false

      - name: Setup Node
        uses: actions/setup-node@v7.0.0
        with:
          node-version: "24"
          registry-url: "https://registry.npmjs.org"
          package-manager-cache: false

      - name: Download verified Node package group
        uses: actions/download-artifact@v8.0.1
        with:
          name: merman-node-npm-package-group
          path: target/node-npm-package-group
          github-token: ${{ github.token }}
          run-id: ${{ needs.validate-inputs.outputs.recovery_run_id != '' && needs.validate-inputs.outputs.recovery_run_id || github.run_id }}

      - name: Verify downloaded Node package group
        env:
          VERSION: ${{ needs.validate-inputs.outputs.version }}
          SOURCE_SHA: ${{ needs.validate-inputs.outputs.source_sha }}
          NPM_DIST_TAG: ${{ needs.validate-inputs.outputs.npm_dist_tag }}
        run: |
          set -euo pipefail
          python3 trusted/scripts/node_package_group.py verify-artifact \
            --manifest target/node-npm-package-group/node-package-group.json \
            --artifact-dir target/node-npm-package-group \
            --descriptor release-source/platforms/node/package-surfaces.json \
            --version "$VERSION" \
            --source-sha "$SOURCE_SHA" \
            --target-dist-tag "$NPM_DIST_TAG"

      - name: Publish npm package group
        run: |
          set -euo pipefail
          python3 trusted/scripts/node_package_group.py reconcile \
            --manifest target/node-npm-package-group/node-package-group.json \
            --artifact-dir target/node-npm-package-group \
            --descriptor release-source/platforms/node/package-surfaces.json \
            --registry https://registry.npmjs.org \
            --report target/node-npm-package-group/reconciliation-report.json

      - name: Upload npm reconciliation report
        if: ${{ always() }}
        uses: actions/upload-artifact@v7.0.1
        with:
          name: merman-node-npm-reconciliation-report
          path: target/node-npm-package-group/reconciliation-report.json
          if-no-files-found: warn