sqlrite-engine 0.1.7

# The "publish" half of the two-workflow release flow. Fires
# automatically when a Release PR (from `release-pr.yml`) merges —
# detects it via the `release: v<semver>` commit message on the
# merge commit. A `workflow_dispatch` fallback lets a human re-run
# the publish side manually when the auto-trigger needs a kick.
#
# Phase 6d: tag-all + publish-crate + publish-ffi + finalize.
# Phase 6e adds publish-desktop.
# Phase 6f adds build-python-wheels + publish-python.
# Phase 6g adds build-nodejs-binaries + publish-nodejs.
# Phases 6h–6i add publish-wasm / publish-go as separate jobs
# to this same file.
#
# Design doc: docs/release-plan.md.
# One-time registry / branch-protection setup: docs/release-secrets.md.

name: Release

on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to (re-)publish. Use only when the auto-trigger needs a manual kick.'
        required: true
        type: string

# `contents: write` — tag creation + GitHub Release uploads.
permissions:
  contents: write

# Only one release at a time across the whole workflow. Back-to-back
# merges of two Release PRs (which should never happen, but still)
# run serially rather than racing on tag creation.
concurrency:
  group: release
  cancel-in-progress: false

jobs:
  # ---------------------------------------------------------------------------
  # Step 1: figure out whether this push commit is actually a release
  # (and extract the version from the commit message), or just a
  # regular push we should ignore. Runs on every push to main.
  detect:
    name: Detect release commit
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.parse.outputs.version }}
      should_release: ${{ steps.parse.outputs.should_release }}
    steps:
      - uses: actions/checkout@v4

      - id: parse
        # On workflow_dispatch, trust the input verbatim (validated
        # by the dispatcher).
        # On push, parse the top line of the HEAD commit message.
        # If it matches `release: vX.Y.Z`, extract and proceed.
        # Anything else is a regular commit — exit silently.
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            VERSION="${{ inputs.version }}"
            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
            echo "should_release=true" >> "$GITHUB_OUTPUT"
            echo "::notice::Manually dispatched release for v$VERSION"
            exit 0
          fi

          # GitHub's default squash-merge title is `<PR title> (#N)` —
          # e.g. `release: v0.1.2 (#18)`. Strip the trailing ` (#N)` so
          # the regex matches both the squash-merge form and the
          # stripped-title form (we still recommend editing to the
          # latter, but should-just-work beats should-remember).
          MSG=$(git log -1 --pretty=%s | sed -E 's/ \(#[0-9]+\)$//')
          if [[ "$MSG" =~ ^release:\ v([0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?)$ ]]; then
            VERSION="${BASH_REMATCH[1]}"
            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
            echo "should_release=true" >> "$GITHUB_OUTPUT"
            echo "::notice::Release commit detected: v$VERSION"
          else
            echo "should_release=false" >> "$GITHUB_OUTPUT"
            echo "::notice::Not a release commit — skipping"
          fi

  # ---------------------------------------------------------------------------
  # Step 2: push per-product tags against the current commit. Runs
  # BEFORE any publish step so a bad version number (e.g., tag
  # already exists for some reason) aborts the whole release cleanly.
  #
  # As of Phase 6g, we tag:
  #   - sqlrite-v<V>           (Rust engine)
  #   - sqlrite-ffi-v<V>       (C FFI prebuilt binaries)
  #   - sqlrite-desktop-v<V>   (Tauri desktop installers)
  #   - sqlrite-py-v<V>        (Python wheels on PyPI)
  #   - sqlrite-node-v<V>      (Node.js N-API bindings on npm)
  #   - v<V>                   (umbrella)
  #
  # Later phases add sqlrite-wasm-v<V>, sdk/go/v<V> as their
  # publish jobs come online.
  #
  # Idempotent on re-run: if a tag already exists (partial-failure
  # scenario where publish-crate succeeded but publish-ffi failed,
  # say), we skip instead of failing. Lets "Re-run failed jobs" in
  # the GitHub UI actually work.
  tag-all:
    name: Tag all products
    needs: detect
    if: needs.detect.outputs.should_release == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # Need tag history to check existing tags.
          fetch-depth: 0

      - name: Configure git identity
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

      - name: Create + push tags
        run: |
          V="${{ needs.detect.outputs.version }}"
          TAGS=(
            "sqlrite-v$V"
            "sqlrite-ffi-v$V"
            "sqlrite-desktop-v$V"
            "sqlrite-py-v$V"
            "sqlrite-node-v$V"
            "v$V"
          )
          for tag in "${TAGS[@]}"; do
            if git rev-parse "$tag" >/dev/null 2>&1; then
              echo "::notice::Tag $tag already exists — skipping (re-run scenario)"
            else
              git tag "$tag"
              echo "Created tag $tag"
            fi
          done
          git push --tags

  # ---------------------------------------------------------------------------
  # Step 3a: publish the Rust engine crate to crates.io + create
  # its per-product GitHub Release. Gated by the `release`
  # environment's required-reviewer rule (a maintainer has to
  # click Approve before this job actually runs).
  publish-crate:
    name: Publish sqlrite crate to crates.io
    needs: [detect, tag-all]
    if: needs.detect.outputs.should_release == 'true'
    runs-on: ubuntu-latest
    environment: release
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable

      - uses: Swatinem/rust-cache@v2
        with:
          shared-key: publish-crate

      - name: cargo publish
        env:
          CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_IO_TOKEN }}
        run: |
          # `--no-verify` skips the rebuild+test that publish does
          # by default — CI already ran on the same commit on the
          # Release PR, so re-running here is duplicate work.
          #
          # Package name on crates.io is `sqlrite-engine`, not
          # `sqlrite` — the latter was taken by an unrelated project
          # (see root Cargo.toml for context). The [lib] name is
          # still `sqlrite`, so downstream code writes `use sqlrite::…`.
          cargo publish -p sqlrite-engine --no-verify

      - name: GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: sqlrite-v${{ needs.detect.outputs.version }}
          name: Rust engine v${{ needs.detect.outputs.version }}
          body: |
            Published to crates.io: https://crates.io/crates/sqlrite-engine/${{ needs.detect.outputs.version }}

            ```toml
            [dependencies]
            sqlrite-engine = "${{ needs.detect.outputs.version }}"
            ```

            ```rust
            // The [lib] name stays `sqlrite`, so the import alias is
            // the short one even though the package name is longer.
            use sqlrite::{Database, ExecutionResult};
            ```

            See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
          generate_release_notes: true

  # ---------------------------------------------------------------------------
  # Step 3b: build `libsqlrite_c` for each supported platform and
  # upload the tarballs to the `sqlrite-ffi-v<V>` GitHub Release.
  #
  # Matrix covers the platforms the Go / Python / Node SDKs' cgo /
  # dlopen paths care about. Note: macos-latest is Apple Silicon
  # (aarch64). A universal binary (x86_64 + aarch64 lipo'd
  # together) is a follow-up — the MVP ships aarch64-only for
  # macOS. Add `macos-13` to the matrix if x86_64 Mac support
  # becomes a real ask.
  publish-ffi:
    name: Publish C FFI (${{ matrix.platform }})
    needs: [detect, tag-all]
    if: needs.detect.outputs.should_release == 'true'
    runs-on: ${{ matrix.os }}
    environment: release
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            platform: linux-x86_64
            shared_lib: libsqlrite_c.so
            static_lib: libsqlrite_c.a
          - os: ubuntu-24.04-arm
            platform: linux-aarch64
            shared_lib: libsqlrite_c.so
            static_lib: libsqlrite_c.a
          - os: macos-latest
            platform: macos-aarch64
            shared_lib: libsqlrite_c.dylib
            static_lib: libsqlrite_c.a
          - os: windows-latest
            platform: windows-x86_64
            shared_lib: sqlrite_c.dll
            static_lib: sqlrite_c.lib
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable

      - uses: Swatinem/rust-cache@v2
        with:
          shared-key: publish-ffi-${{ matrix.platform }}

      - name: Build libsqlrite_c
        run: cargo build --release -p sqlrite-ffi

      - name: Package tarball
        shell: bash
        run: |
          V="${{ needs.detect.outputs.version }}"
          STAGE="sqlrite-ffi-v$V-${{ matrix.platform }}"
          mkdir -p "$STAGE/lib" "$STAGE/include"
          cp "target/release/${{ matrix.shared_lib }}" "$STAGE/lib/"
          cp "target/release/${{ matrix.static_lib }}" "$STAGE/lib/" 2>/dev/null || \
            echo "::warning::static lib ${{ matrix.static_lib }} not found on ${{ matrix.platform }} — shipping shared lib only"
          cp "sqlrite-ffi/include/sqlrite.h" "$STAGE/include/"
          # README pointer so end users know what they're looking at
          # when they untar the download.
          cat > "$STAGE/README" <<EOF
          SQLRite C FFI v$V — ${{ matrix.platform }}

          Contents:
            lib/ ${{ matrix.shared_lib }}  — dynamic library to link against
            lib/ ${{ matrix.static_lib }}  — static library (if present)
            include/ sqlrite.h             — C header

          Full docs: https://github.com/joaoh82/rust_sqlite/blob/main/sqlrite-ffi/README.md
          EOF
          tar czf "$STAGE.tar.gz" "$STAGE"
          # Emit the path for the upload step below.
          echo "ASSET=$STAGE.tar.gz" >> "$GITHUB_ENV"

      - name: Upload to GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: sqlrite-ffi-v${{ needs.detect.outputs.version }}
          name: C FFI v${{ needs.detect.outputs.version }}
          body: |
            Prebuilt `libsqlrite_c` for every supported platform, plus the `sqlrite.h` header.

            Download the tarball for your platform, extract, and link:

            ```
            tar xzf sqlrite-ffi-v${{ needs.detect.outputs.version }}-<platform>.tar.gz
            # lib/   — dynamic + static libraries
            # include/sqlrite.h — header to #include
            ```

            See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
          files: ${{ env.ASSET }}
          generate_release_notes: true

  # ---------------------------------------------------------------------------
  # Step 3c: build the Tauri desktop app for each supported platform
  # and upload the installers to the `sqlrite-desktop-v<V>` GitHub
  # Release. (Phase 6e.)
  #
  # Matrix mirrors publish-ffi's — same three OS families, same
  # "aarch64 on macOS, x86_64 elsewhere" choice. The actual installer
  # formats per platform come from Tauri's bundler, not the matrix:
  #   - ubuntu-22.04 → AppImage + .deb           (x86_64)
  #   - macos-latest → .dmg                       (aarch64)
  #   - windows-latest → .msi                     (x86_64)
  #
  # ubuntu-22.04 (not ubuntu-latest) is deliberate: AppImage links
  # glibc at build time, so building on 22.04 (glibc 2.35) yields
  # an AppImage that runs on any distro with glibc ≥ 2.35 — which
  # covers everything shipped since 2022. Building on ubuntu-latest
  # (24.04, glibc 2.39) would produce an AppImage that refuses to
  # launch on Debian 12 / Ubuntu 22.04 and older.
  #
  # macOS universal (x86_64 + aarch64 lipo'd together) + Linux
  # aarch64 desktop are follow-ups — same MVP-simplicity reasoning
  # as publish-ffi. Apple Silicon is the majority of Mac downloads
  # and x86_64 Linux is the majority of Linux downloads, so this
  # covers 95%+ of users on day one.
  #
  # Installers ship **unsigned** — Phase 6.1 wires up Apple
  # Developer ID + Windows code-signing cert. Unsigned installers
  # trigger the expected "unidentified developer" / SmartScreen
  # warnings; the release body explains how to bypass them.
  publish-desktop:
    name: Publish desktop (${{ matrix.platform }})
    needs: [detect, tag-all]
    if: needs.detect.outputs.should_release == 'true'
    runs-on: ${{ matrix.os }}
    environment: release
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-22.04
            platform: linux-x86_64
          - os: macos-latest
            platform: macos-aarch64
          - os: windows-latest
            platform: windows-x86_64
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: desktop/package-lock.json

      - uses: dtolnay/rust-toolchain@stable

      - uses: Swatinem/rust-cache@v2
        with:
          shared-key: publish-desktop-${{ matrix.platform }}
          workspaces: './ -> target'

      # Linux-only: Tauri's webview backend is webkit2gtk, which
      # isn't preinstalled on GitHub runners. libayatana-appindicator
      # / librsvg2 / patchelf are the rest of the standard Tauri
      # Linux build kit. Matches the `desktop-build` job in ci.yml.
      - name: Install Tauri Linux deps
        if: matrix.os == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libwebkit2gtk-4.1-dev \
            libayatana-appindicator3-dev \
            librsvg2-dev \
            patchelf

      - name: npm ci
        working-directory: desktop
        run: npm ci

      # Icons (icon.ico, icon.icns, size-specific PNGs for Linux,
      # mobile assets) are pre-generated in the repo via `npx tauri
      # icon src-tauri/icons/icon.png` and committed to
      # `desktop/src-tauri/icons/`. That keeps CI deterministic and
      # saves ~10s per matrix cell; the tradeoff is that anyone
      # changing `icon.png` needs to re-run `tauri icon` locally and
      # commit the regenerated assets (PR review catches this).

      # tauri-action does: frontend build (via beforeBuildCommand) →
      # `cargo tauri build` → bundle installers per platform → upload
      # each installer to the target GitHub Release. It reads
      # tauri.conf.json for bundle config, so flipping `bundle.active`
      # from `false` to `true` there is what actually causes installers
      # to get produced. `tagName` is templated so the action doesn't
      # create its own tag — we already did that in `tag-all`.
      - name: Build + upload installers
        uses: tauri-apps/tauri-action@v0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tagName: sqlrite-desktop-v${{ needs.detect.outputs.version }}
          releaseName: Desktop v${{ needs.detect.outputs.version }}
          releaseBody: |
            SQLRite desktop app — unsigned installers. This release wave ships:

            - **Linux**: `.AppImage` + `.deb` (Debian/Ubuntu) + `.rpm` (Fedora/RHEL), x86_64
            - **macOS**: `.dmg` + raw `.app.tar.gz`, Apple Silicon (aarch64). Intel Macs not supported yet — tracked as a Phase 6e follow-up (universal dmg).
            - **Windows**: `.msi` + `.exe` (NSIS installer), x86_64

            ### ⚠️ Unsigned installer warnings

            Installers aren't code-signed yet (Phase 6.1 wires up Apple Developer ID + Windows code-signing). First-launch warnings to expect:

            **macOS — "SQLRite is damaged and can't be opened" or "unidentified developer":**

            ```bash
            xattr -cr /Applications/SQLRite.app
            ```

            This strips the `com.apple.quarantine` attribute your browser attached on download. macOS Gatekeeper shows "damaged" (not the gentler "unidentified developer") because Tauri ad-hoc signs the binary — Apple Silicon *requires* a signature, even an ad-hoc one, but quarantined ad-hoc signatures trip a stricter Gatekeeper path. The app is fine; the signature just isn't from a registered Apple Developer ID.

            **Windows — SmartScreen "Windows protected your PC":**

            Click "More info" → "Run anyway".

            **Linux — AppImage:**

            ```bash
            chmod +x SQLRite_*_amd64.AppImage
            ./SQLRite_*_amd64.AppImage
            ```

            See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
          releaseDraft: false
          prerelease: false
          projectPath: desktop
          # tauri-action's default is to create the release if it
          # doesn't exist. Since we want the release to aggregate
          # artifacts across all three matrix jobs, the first job
          # to finish creates it; the other two upload additional
          # files to the same release. (action is idempotent on
          # this — it uses `tagName` as the identity key.)

  # ---------------------------------------------------------------------------
  # Step 3d: build Python wheels for every supported platform.
  # (Phase 6f — build half; publish half lives in the next job.)
  #
  # Why the split: PyPI expects wheels to be uploaded as one
  # batch — if publish-python-wheels had publish logic inline,
  # each matrix cell would race to upload its wheel independently,
  # and a failure mid-matrix would leave PyPI with a partial wave.
  # The two-job shape lets us aggregate every wheel (+ sdist) into
  # one `dist/` directory and do the upload as a single atomic
  # step in the `publish-python` job below.
  #
  # Matrix mirrors publish-ffi / publish-desktop — same four
  # OS / arch combinations. abi3-py38 means each platform gets
  # ONE wheel that works on every CPython ≥ 3.8, so we don't
  # need a per-Python-version matrix axis.
  build-python-wheels:
    name: Build Python wheel (${{ matrix.platform }})
    needs: [detect, tag-all]
    if: needs.detect.outputs.should_release == 'true'
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            target: x86_64
            platform: linux-x86_64
            manylinux: auto
          - os: ubuntu-24.04-arm
            target: aarch64
            platform: linux-aarch64
            manylinux: auto
          - os: macos-latest
            target: aarch64
            platform: macos-aarch64
            manylinux: ""
          - os: windows-latest
            target: x64
            platform: windows-x86_64
            manylinux: ""
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          # 3.10 is the build interpreter; abi3 means the wheel
          # itself runs on every CPython ≥ 3.8. Any recent
          # Python on the runner would work — 3.10 is just
          # well-supported + cached on all runner images.
          python-version: '3.10'

      - uses: dtolnay/rust-toolchain@stable

      - uses: Swatinem/rust-cache@v2
        with:
          shared-key: build-python-wheels-${{ matrix.platform }}

      # `maturin-action` builds + packages the wheel. For Linux
      # `manylinux: auto` means it runs inside a manylinux2014
      # container so glibc gets baked at an old-enough version
      # that the wheel runs on any distro shipped since ~2014.
      # macOS / Windows don't use manylinux — the wheel tags
      # reflect the specific OS version it was built on.
      - name: Build wheel
        uses: PyO3/maturin-action@v1
        with:
          working-directory: sdk/python
          target: ${{ matrix.target }}
          args: --release --out dist
          manylinux: ${{ matrix.manylinux }}

      - name: Upload wheel artifact
        uses: actions/upload-artifact@v4
        with:
          name: python-wheel-${{ matrix.platform }}
          path: sdk/python/dist/*.whl
          if-no-files-found: error
          retention-days: 1

  # ---------------------------------------------------------------------------
  # Step 3e: build the Python source distribution.
  #
  # Uploaded alongside the wheels so users on odd platforms not
  # covered by our wheel matrix (FreeBSD, alpine aarch64, etc.)
  # can still `pip install sqlrite` and get a source build
  # (requires their local Rust toolchain, which is the standard
  # fallback path for any PyO3 crate).
  build-python-sdist:
    name: Build Python sdist
    needs: [detect, tag-all]
    if: needs.detect.outputs.should_release == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: Build sdist
        uses: PyO3/maturin-action@v1
        with:
          working-directory: sdk/python
          command: sdist
          args: --out dist

      - name: Upload sdist artifact
        uses: actions/upload-artifact@v4
        with:
          name: python-sdist
          path: sdk/python/dist/*.tar.gz
          if-no-files-found: error
          retention-days: 1

  # ---------------------------------------------------------------------------
  # Step 3f: aggregate every wheel + the sdist, upload to PyPI
  # via OIDC trusted publishing, and cut the per-product
  # `sqlrite-py-v<V>` GitHub Release.
  #
  # OIDC trusted publishing: no long-lived PyPI API token exists
  # anywhere. The `permissions: id-token: write` block below
  # lets `pypa/gh-action-pypi-publish` mint a short-lived OIDC
  # token, exchange it at PyPI for a one-time upload token, and
  # push every wheel. PyPI-side config lives on the `sqlrite`
  # project's settings page — see docs/release-secrets.md for
  # the one-time trusted-publisher registration.
  publish-python:
    name: Publish Python wheels to PyPI
    needs: [detect, tag-all, build-python-wheels, build-python-sdist]
    if: needs.detect.outputs.should_release == 'true'
    runs-on: ubuntu-latest
    environment: release
    permissions:
      # OIDC: required for PyPI trusted-publisher token exchange.
      id-token: write
      # For the softprops/action-gh-release step at the end.
      contents: write
    steps:
      - uses: actions/checkout@v4

      # Pull every wheel artifact (one per matrix platform) +
      # the sdist into a single `dist/` directory.
      - name: Download wheel artifacts
        uses: actions/download-artifact@v4
        with:
          pattern: python-wheel-*
          path: dist
          merge-multiple: true

      - name: Download sdist artifact
        uses: actions/download-artifact@v4
        with:
          name: python-sdist
          path: dist

      - name: List files about to be uploaded
        run: ls -la dist/

      # Single atomic upload of all wheels + sdist. If any file
      # fails to upload, none are published — no partial wave
      # on PyPI.
      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          packages-dir: dist
          # Keep `skip-existing: false` so a re-run of this job
          # (after a partial-failure scenario) fails loudly rather
          # than silently ignoring already-uploaded files.
          skip-existing: false

      - name: GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: sqlrite-py-v${{ needs.detect.outputs.version }}
          name: Python v${{ needs.detect.outputs.version }}
          body: |
            Published to PyPI: https://pypi.org/project/sqlrite/${{ needs.detect.outputs.version }}/

            ```bash
            pip install sqlrite==${{ needs.detect.outputs.version }}
            ```

            ```python
            import sqlrite
            conn = sqlrite.connect(":memory:")
            conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
            conn.execute("INSERT INTO users (name) VALUES (?)", ("alice",))
            for row in conn.execute("SELECT * FROM users"):
                print(row)
            ```

            **Wheels in this release:**
            - Linux x86_64 (manylinux2014 or newer)
            - Linux aarch64 (manylinux2014 or newer)
            - macOS aarch64 (Apple Silicon)
            - Windows x86_64
            - Source distribution (`.tar.gz`) — builds from source on other platforms via a local Rust toolchain

            All wheels are `abi3-py38`, so one wheel per platform works on every CPython ≥ 3.8.

            See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
          files: dist/*
          generate_release_notes: true

  # ---------------------------------------------------------------------------
  # Step 3g: build Node.js N-API binaries for every supported
  # platform. (Phase 6g — build half; publish half lives in the
  # next job.)
  #
  # Architecture: the "bundled binaries" approach, not napi-rs's
  # newer optional-deps-per-platform pattern. The main `sqlrite`
  # npm package ships every platform's `.node` binary inside one
  # tarball; napi-rs's generated `index.js` dispatcher picks the
  # right one at require time based on process.platform / arch.
  # Simpler for MVP than maintaining N+1 npm packages; the cost
  # is a ~15 MiB tarball instead of a ~4 MiB per-platform download,
  # which is fine for a database driver people install once.
  #
  # Same build/publish split as publish-python for the same
  # reason: npm expects one `npm publish` invocation per package
  # version. If every matrix cell published independently, a
  # partial-failure would put some-but-not-all binaries on npm
  # with no clean rollback.
  #
  # Matrix mirrors publish-ffi / publish-desktop / publish-python.
  # Naming convention for the `.node` file is napi-rs's own: the
  # platform triple is baked into the filename, e.g.,
  # `sqlrite.linux-x64-gnu.node` vs `sqlrite.darwin-arm64.node`.
  # The `files` glob in sdk/nodejs/package.json matches on
  # `sqlrite.*.node`, so whichever binaries land in the directory
  # at publish time get included in the tarball.
  build-nodejs-binaries:
    name: Build Node.js binary (${{ matrix.platform }})
    needs: [detect, tag-all]
    if: needs.detect.outputs.should_release == 'true'
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            platform: linux-x86_64
            napi_triple: linux-x64-gnu
          - os: ubuntu-24.04-arm
            platform: linux-aarch64
            napi_triple: linux-arm64-gnu
          - os: macos-latest
            platform: macos-aarch64
            napi_triple: darwin-arm64
          - os: windows-latest
            platform: windows-x86_64
            napi_triple: win32-x64-msvc
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: sdk/nodejs/package-lock.json

      - uses: dtolnay/rust-toolchain@stable

      - uses: Swatinem/rust-cache@v2
        with:
          shared-key: build-nodejs-${{ matrix.platform }}

      - name: Install npm deps
        working-directory: sdk/nodejs
        run: npm ci

      # `napi build --platform --release` produces:
      #   - sqlrite.<napi_triple>.node  (the actual binary)
      #   - index.js                    (platform-dispatch loader)
      #   - index.d.ts                  (TypeScript types)
      # We upload all three but only index.js/d.ts from the
      # Linux x86_64 cell (they're identical across platforms
      # since napi generates platform-agnostic dispatch code).
      - name: Build native binary
        working-directory: sdk/nodejs
        run: npm run build

      - name: Verify binary exists
        working-directory: sdk/nodejs
        shell: bash
        run: |
          ls -la sqlrite.*.node
          # Fail early if napi produced an unexpected filename —
          # otherwise the publish step would silently ship an
          # incomplete tarball.
          test -f "sqlrite.${{ matrix.napi_triple }}.node"

      - name: Upload .node binary
        uses: actions/upload-artifact@v4
        with:
          name: nodejs-binary-${{ matrix.platform }}
          path: sdk/nodejs/sqlrite.${{ matrix.napi_triple }}.node
          if-no-files-found: error
          retention-days: 1

      # Only Linux x86_64 uploads the shared dispatcher files.
      # These are identical regardless of build platform (they're
      # just require-the-right-.node glue), so we only need one
      # copy in the final npm tarball.
      - name: Upload JS dispatcher (linux-x86_64 only)
        if: matrix.platform == 'linux-x86_64'
        uses: actions/upload-artifact@v4
        with:
          name: nodejs-dispatcher
          path: |
            sdk/nodejs/index.js
            sdk/nodejs/index.d.ts
          if-no-files-found: error
          retention-days: 1

  # ---------------------------------------------------------------------------
  # Step 3h: aggregate every platform's `.node` binary + the JS
  # dispatcher into sdk/nodejs/, publish to npm via OIDC trusted
  # publishing, and cut the per-product `sqlrite-node-v<V>`
  # GitHub Release.
  #
  # OIDC trusted publishing: similar to the PyPI setup in
  # publish-python. `permissions: id-token: write` lets npm mint
  # a short-lived OIDC token, which `npm publish --provenance`
  # exchanges for a one-time upload token. No NPM_TOKEN secret.
  # One-time trusted-publisher config on npmjs.com — see
  # docs/release-secrets.md.
  #
  # `--provenance` also attaches a signed attestation linking
  # the package to this exact GitHub Actions workflow run (via
  # sigstore, same mechanism as PyPI's PEP 740). Users who care
  # about supply-chain can verify it with `npm audit signatures`.
  publish-nodejs:
    name: Publish Node.js package to npm
    needs: [detect, tag-all, build-nodejs-binaries]
    if: needs.detect.outputs.should_release == 'true'
    runs-on: ubuntu-latest
    environment: release
    permissions:
      # OIDC for npm trusted publisher + provenance signing.
      id-token: write
      # For softprops/action-gh-release step at the end.
      contents: write
    steps:
      - uses: actions/checkout@v4

      # NOTE: deliberately NO `registry-url:` here. setting that
      # makes setup-node generate an `.npmrc` with
      # `_authToken=${NODE_AUTH_TOKEN}`, which forces npm into
      # token-based auth and *bypasses* the trusted-publisher
      # OIDC pathway entirely. The v0.1.5 canary blew up on this
      # exact issue: `404 Not Found - PUT ... is not in this
      # registry` because npm sent an empty/missing
      # NODE_AUTH_TOKEN instead of minting an OIDC token.
      #
      # With registry-url omitted, no `.npmrc` is generated, and
      # npm CLI ≥ 11.5 auto-detects the GitHub Actions OIDC
      # environment (via ACTIONS_ID_TOKEN_REQUEST_URL +
      # permissions: id-token: write below), mints an OIDC token,
      # and exchanges it at npm for a one-time publish token. The
      # public default registry is fine — that's where
      # registry.npmjs.org lives anyway.
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      # Node 20 LTS ships with npm 10.x, but trusted publishing
      # auto-detection landed in npm 11.5. Force-upgrade so we
      # don't depend on the runner image happening to ship a
      # recent-enough npm.
      - name: Upgrade npm to latest (need 11.5+ for trusted publishing)
        run: npm install -g npm@latest

      # Pull every platform's `.node` binary plus the JS
      # dispatcher into sdk/nodejs/, overlaying them on top of
      # the checked-out package.json / package-lock.json / etc.
      - name: Download .node binaries
        uses: actions/download-artifact@v4
        with:
          pattern: nodejs-binary-*
          path: sdk/nodejs
          merge-multiple: true

      - name: Download JS dispatcher
        uses: actions/download-artifact@v4
        with:
          name: nodejs-dispatcher
          path: sdk/nodejs

      - name: List publish payload + OIDC env diagnostics
        working-directory: sdk/nodejs
        run: |
          ls -la
          echo "---"
          npm --version
          echo "---"
          # Confirm the OIDC env vars GitHub Actions auto-sets when
          # `permissions: id-token: write` is granted. If either of
          # these is empty, OIDC token exchange CAN'T happen and
          # npm publish will fall back to "no auth available".
          # Just print whether they're set, not their values
          # (the URL has a trailing token-issuance path; treat as
          # sensitive).
          echo "ACTIONS_ID_TOKEN_REQUEST_URL  is set: ${ACTIONS_ID_TOKEN_REQUEST_URL:+yes}${ACTIONS_ID_TOKEN_REQUEST_URL:-NO}"
          echo "ACTIONS_ID_TOKEN_REQUEST_TOKEN is set: ${ACTIONS_ID_TOKEN_REQUEST_TOKEN:+yes}${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-NO}"
          echo "---"
          # Dry-run the pack to see exactly what ends up in the
          # published tarball. A missing .node file or a stray
          # devDep pulled in by accident would be visible here.
          npm pack --dry-run

      # Single atomic publish via OIDC trusted publisher.
      #
      # The `--provenance` flag is what tells npm CLI to use the
      # OIDC code path. Without it, npm only checks for `_authToken`
      # config and gives up with ENEEDAUTH (this happened on the
      # v0.1.6 canary attempt that ran without the flag — npm
      # never even tried OIDC). With it, npm:
      #   1. Reads ACTIONS_ID_TOKEN_REQUEST_URL +
      #      ACTIONS_ID_TOKEN_REQUEST_TOKEN from the GHA env
      #   2. Mints an OIDC token bearing the workflow's identity
      #      claims (repo, environment, workflow filename, etc.)
      #   3. Exchanges it at npm for a one-time publish token
      #   4. Publishes the package + attaches a sigstore-signed
      #      provenance attestation linking the artifact to this
      #      exact workflow run
      #
      # The previous v0.1.5 failure with `--provenance` set was a
      # different bug — `registry-url` on setup-node was generating
      # an `.npmrc` that forced token-auth and bypassed OIDC. With
      # registry-url removed (this file's previous fix) and
      # `--provenance` restored, both bugs are addressed.
      #
      # `--access public` is REQUIRED because `@joaoh82/sqlrite`
      # is a scoped package and scoped packages default to private;
      # without the flag, npm rejects the upload for a free-tier
      # account that can't host private packages.
      #
      # `--loglevel verbose` makes auth/transport errors
      # diagnosable from the run log without re-running with
      # debug-on. Cheap insurance against another silent failure.
      - name: Publish to npm
        working-directory: sdk/nodejs
        run: npm publish --access public --provenance --loglevel verbose

      - name: GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: sqlrite-node-v${{ needs.detect.outputs.version }}
          name: Node.js v${{ needs.detect.outputs.version }}
          body: |
            Published to npm: https://www.npmjs.com/package/@joaoh82/sqlrite/v/${{ needs.detect.outputs.version }}

            ```bash
            npm install @joaoh82/sqlrite@${{ needs.detect.outputs.version }}
            ```

            ```javascript
            const { Database } = require('@joaoh82/sqlrite');

            const db = new Database(':memory:');
            db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
            const stmt = db.prepare('INSERT INTO users (name) VALUES (?)');
            stmt.run('alice');

            for (const row of db.prepare('SELECT * FROM users').iterate()) {
              console.log(row);
            }
            ```

            **Binaries bundled in this release:**
            - Linux x86_64 (`sqlrite.linux-x64-gnu.node`)
            - Linux aarch64 (`sqlrite.linux-arm64-gnu.node`)
            - macOS aarch64 (`sqlrite.darwin-arm64.node`)
            - Windows x86_64 (`sqlrite.win32-x64-msvc.node`)

            The package's `index.js` dispatcher auto-selects the right binary at require time — no platform-specific install step.

            Verify package provenance:
            ```bash
            npm audit signatures
            ```

            See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
          generate_release_notes: true

  # ---------------------------------------------------------------------------
  # Step 4: create the umbrella GitHub Release. Runs after all
  # publish-* jobs succeed. Uses GitHub's native auto-generated
  # release notes so the changelog is "everything between the
  # previous v* tag and this one" — curated via .github/release.yml
  # config if we add one later.
  finalize:
    name: Finalize umbrella release
    needs: [detect, publish-crate, publish-ffi, publish-desktop, publish-python, publish-nodejs]
    if: needs.detect.outputs.should_release == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Umbrella GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: v${{ needs.detect.outputs.version }}
          name: v${{ needs.detect.outputs.version }}
          body: |
            **SQLRite v${{ needs.detect.outputs.version }}**

            Per-product releases in this wave:

            - 🦀 [Rust engine](../../releases/tag/sqlrite-v${{ needs.detect.outputs.version }}) → [crates.io](https://crates.io/crates/sqlrite-engine/${{ needs.detect.outputs.version }})
            - 🔧 [C FFI](../../releases/tag/sqlrite-ffi-v${{ needs.detect.outputs.version }}) — prebuilt `libsqlrite_c` for Linux x86_64/aarch64, macOS aarch64, Windows x86_64
            - 🖥️ [Desktop](../../releases/tag/sqlrite-desktop-v${{ needs.detect.outputs.version }}) — unsigned installers for Linux (AppImage + deb), macOS (dmg aarch64), Windows (msi)
            - 🐍 [Python](../../releases/tag/sqlrite-py-v${{ needs.detect.outputs.version }}) → [PyPI](https://pypi.org/project/sqlrite/${{ needs.detect.outputs.version }}/) — abi3-py38 wheels for Linux x86_64/aarch64, macOS aarch64, Windows x86_64 + sdist
            - 🟢 [Node.js](../../releases/tag/sqlrite-node-v${{ needs.detect.outputs.version }}) → [npm](https://www.npmjs.com/package/@joaoh82/sqlrite/v/${{ needs.detect.outputs.version }}) — N-API bindings with prebuilt `.node` binaries for Linux x86_64/aarch64, macOS aarch64, Windows x86_64

            _WASM / Go SDKs land as their publish jobs come online (Phases 6h–6i)._

            ---

            Auto-generated changelog below ↓
          generate_release_notes: true