refactor(scripts): move repository tooling to Node 24

.changeset/node-repository-tooling.md

@@ -0,0 +1,4 @@
+---
+---
+
+This refactor changes repository tooling, tests, and contributor setup only; it does not change shipped application or container behavior.

.github/actions/setup-bun/action.yml

@@ -7,6 +7,10 @@ runs:
       shell: bash
       run: |
         echo "HUSKY=0" >> "$GITHUB_ENV"
+    - name: Setup Node.js
+      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      with:
+        node-version-file: package.json
     - name: Setup Bun
       uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
       with:

.github/workflows/cd-docs-teardown.yml

@@ -27,12 +27,12 @@ jobs:
       - name: Teardown Surge.sh preview
         env:
           SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}
-        run: bun --bun surge teardown "$PREVIEW_URL" --token "$SURGE_TOKEN"
+        run: ./node_modules/.bin/surge teardown "$PREVIEW_URL" --token "$SURGE_TOKEN"
         continue-on-error: true
       - name: Teardown Storybook preview
         env:
           SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}
-        run: bun --bun surge teardown "$STORYBOOK_PREVIEW_URL" --token "$SURGE_TOKEN"
+        run: ./node_modules/.bin/surge teardown "$STORYBOOK_PREVIEW_URL" --token "$SURGE_TOKEN"
         continue-on-error: true
 
       - name: Update PR comment

.github/workflows/cd-docs.yml

@@ -98,7 +98,7 @@ jobs:
       - name: Deploy to Surge.sh
         env:
           SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}
-        run: bun --bun surge ./docs-build "$PREVIEW_URL" --token "$SURGE_TOKEN"
+        run: ./node_modules/.bin/surge ./docs-build "$PREVIEW_URL" --token "$SURGE_TOKEN"
       - uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4
         with:
           header: docs-preview

.github/workflows/ci-profile.yml

@@ -56,7 +56,7 @@ jobs:
       - name: Enforce performance budgets
         if: success() && github.ref_name == github.event.repository.default_branch
         run: |
-          bun scripts/check-ci-performance.ts ci-metrics/server-integration-profile.json ci-profile-history
+          node scripts/check-ci-performance.ts ci-metrics/server-integration-profile.json ci-profile-history
           mkdir -p ci-profile-history
           cp ci-metrics/server-integration-profile.json "ci-profile-history/${{ github.run_id }}.json"
 

.github/workflows/ci-tests.yml

@@ -209,7 +209,7 @@ jobs:
         env:
           PREVIEW_URL: ls1intum-hephaestus-storybook-pr-${{ github.event.number }}.surge.sh
           SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}
-        run: bun --bun surge ./webapp/storybook-static "$PREVIEW_URL" --token "$SURGE_TOKEN"
+        run: ./node_modules/.bin/surge ./webapp/storybook-static "$PREVIEW_URL" --token "$SURGE_TOKEN"
 
       - name: Add Storybook preview to the pull request
         if: steps.storybook_preview.outcome == 'success'

.github/workflows/cleanup-preview.yml

@@ -59,7 +59,7 @@ jobs:
         continue-on-error: true
         env:
           COOLIFY_WEBHOOK_SECRET: ${{ secrets.COOLIFY_PREVIEW_WEBHOOK_SECRET }}
-        run: bun scripts/coolify-preview.ts close
+        run: node scripts/coolify-preview.ts close
 
       - name: Record that teardown was requested
         id: tombstone

.github/workflows/deploy-locked-compose.yml

@@ -79,7 +79,7 @@ jobs:
         run: |
           set -euo pipefail
           asset="release-${RELEASE}.json"
-          bun scripts/release-image-lock.ts "$RUNNER_TEMP/verified-release/$asset" \
+          node scripts/release-image-lock.ts "$RUNNER_TEMP/verified-release/$asset" \
             "$RUNNER_TEMP/verified-release/manifest.json" "$RELEASE" release-lock.env
 
           render() {

.github/workflows/deploy-preview.yml

@@ -77,7 +77,7 @@ jobs:
           GHCR_TOKEN: ${{ github.token }}
           GH_TOKEN: ${{ github.token }}
           HEAD_SHA: ${{ steps.context.outputs.head_sha }}
-        run: bun scripts/coolify-preview.ts images
+        run: node scripts/coolify-preview.ts images
 
       - name: Recheck opt-in and head before queueing
         id: recheck
@@ -132,7 +132,7 @@ jobs:
           AUTHOR_ASSOCIATION: ${{ steps.context.outputs.author_association }}
           HEAD_REF: ${{ steps.context.outputs.head_ref }}
           BASE_REF: ${{ steps.context.outputs.base_ref }}
-        run: bun scripts/coolify-preview.ts queue
+        run: node scripts/coolify-preview.ts queue
 
       - name: Wait for Coolify and verify the preview
         id: wait
@@ -143,7 +143,7 @@ jobs:
           EXPECTED_SHA: ${{ steps.context.outputs.head_sha }}
           PR_NUMBER: ${{ steps.context.outputs.pr_number }}
           PREVIEW_URL: ${{ steps.context.outputs.preview_url }}
-        run: bun scripts/coolify-preview.ts wait
+        run: node scripts/coolify-preview.ts wait
 
       - name: Finalize the GitHub deployment
         id: finalize

.github/workflows/reconcile-previews.yml

@@ -100,7 +100,7 @@ jobs:
           HEAD_REF: ${{ steps.pull.outputs.head_ref }}
           HEAD_SHA: ${{ steps.pull.outputs.head_sha }}
           BASE_REF: ${{ steps.pull.outputs.base_ref }}
-        run: bun scripts/coolify-preview.ts close
+        run: node scripts/coolify-preview.ts close
 
       - name: Retire the GitHub preview deployments
         if: steps.pull.outputs.stale == 'true' && steps.close.outcome == 'success'

.github/workflows/release.yml

@@ -272,7 +272,7 @@ jobs:
                 -o "syft-json=evidence/$image-$suffix.syft.json" \
                 -o "spdx-json=evidence/$image-$suffix.spdx.json" \
                 -o "cyclonedx-json=evidence/$image-$suffix.cdx.json"
-              bun scripts/check-release-sbom.ts \
+              node scripts/check-release-sbom.ts \
                 "evidence/$image-$suffix.syft.json" \
                 "evidence/$image-$suffix.spdx.json" \
                 "evidence/$image-$suffix.cdx.json" \
@@ -282,7 +282,7 @@ jobs:
               jq -e --arg ref "$platform_ref" \
                 '.ArtifactName == $ref and (.Results | type == "array")' \
                 "evidence/$image-$suffix.license.json" >/dev/null
-              bun scripts/check-release-vulnerabilities.ts "$image" "$platform" "$platform_digest" "$repository" \
+              node scripts/check-release-vulnerabilities.ts "$image" "$platform" "$platform_digest" "$repository" \
                 "evidence/$image-$suffix.trivy.json" security/vulnerability-policy.json \
                 "evidence/$image-$suffix.policy.json"
               if [ "$provenance" = first-party ]; then
@@ -356,7 +356,7 @@ jobs:
                   indexDigest: .[0].indexDigest,
                   platforms: (map({key: .platform, value: .digest}) | from_entries)})}' \
             evidence/manifest.json > "$ASSET"
-          bun scripts/release-image-lock.ts "$ASSET" evidence/manifest.json \
+          node scripts/release-image-lock.ts "$ASSET" evidence/manifest.json \
             "v${VERSION}" /tmp/release-lock.env
           echo "asset-path=$ASSET" >> "$GITHUB_OUTPUT"
           jq . "$ASSET"
@@ -457,7 +457,7 @@ jobs:
             --certificate-identity 'https://github.com/ls1intum/Hephaestus/.github/workflows/release.yml@refs/heads/main' \
             --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
             "evidence/$lock"
-          bun scripts/release-image-lock.ts "evidence/$lock" evidence/manifest.json \
+          node scripts/release-image-lock.ts "evidence/$lock" evidence/manifest.json \
             "$TAG_NAME" /tmp/release-lock.env
           jq -e --slurpfile inventory evidence/release-images.json \
             '.schemaVersion == 1 and
@@ -468,7 +468,7 @@ jobs:
           jq -er '.subjects[] | [.image, .platform, .digest, .repository, .provenance] | @tsv' evidence/manifest.json |
           while IFS=$'\t' read -r image platform digest repository provenance; do
             suffix=${platform//\//-}
-            bun scripts/check-release-sbom.ts \
+            node scripts/check-release-sbom.ts \
               "evidence/$image-$suffix.syft.json" \
               "evidence/$image-$suffix.spdx.json" \
               "evidence/$image-$suffix.cdx.json" \
@@ -480,7 +480,7 @@ jobs:
             jq -e --arg ref "$repository@$digest" \
               '.ArtifactName == $ref and (.Results | type == "array")' \
               "evidence/$image-$suffix.license.json" >/dev/null
-            bun scripts/check-release-vulnerabilities.ts "$image" "$platform" "$digest" "$repository" \
+            node scripts/check-release-vulnerabilities.ts "$image" "$platform" "$digest" "$repository" \
               "evidence/$image-$suffix.trivy.json" evidence/vulnerability-policy.json \
               /tmp/policy.json
             cmp "evidence/$image-$suffix.policy.json" /tmp/policy.json

.github/workflows/rescan-release-images.yml

@@ -45,7 +45,7 @@ jobs:
           jq -er '.subjects[] | [.image, .platform, .indexDigest, .digest, .repository] | @tsv' release-evidence/manifest.json |
           while IFS=$'\t' read -r image platform index_digest digest repository; do
             suffix=${platform//\//-}
-            bun scripts/check-release-sbom.ts \
+            node scripts/check-release-sbom.ts \
               "release-evidence/$image-$suffix.syft.json" \
               "release-evidence/$image-$suffix.spdx.json" \
               "release-evidence/$image-$suffix.cdx.json" \
@@ -57,7 +57,7 @@ jobs:
             jq -e --arg ref "$repository@$digest" \
               '.ArtifactName == $ref and (.Results | type == "array")' \
               "release-evidence/$image-$suffix.license.json" >/dev/null
-            bun scripts/check-release-vulnerabilities.ts "$image" "$platform" "$digest" "$repository" \
+            node scripts/check-release-vulnerabilities.ts "$image" "$platform" "$digest" "$repository" \
               "release-evidence/$image-$suffix.trivy.json" \
               release-evidence/vulnerability-policy.json /tmp/policy.json
             cmp "release-evidence/$image-$suffix.policy.json" /tmp/policy.json
@@ -72,7 +72,7 @@ jobs:
             --certificate-identity 'https://github.com/ls1intum/Hephaestus/.github/workflows/release.yml@refs/heads/main' \
             --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
             "release-evidence/$lock"
-          bun scripts/release-image-lock.ts "release-evidence/$lock" \
+          node scripts/release-image-lock.ts "release-evidence/$lock" \
             release-evidence/manifest.json "$tag" /tmp/release-lock.env
       - name: Rescan immutable subjects
         env:
@@ -91,7 +91,7 @@ jobs:
           while IFS=$'\t' read -r image platform digest repository; do
             suffix=${platform//\//-}
             trivy image --scanners vuln --format json --output "reports/$image-$suffix.json" "$repository@$digest"
-            bun scripts/check-release-vulnerabilities.ts "$image" "$platform" "$digest" "$repository" \
+            node scripts/check-release-vulnerabilities.ts "$image" "$platform" "$digest" "$repository" \
               "reports/$image-$suffix.json" security/vulnerability-policy.json \
               "reports/$image-$suffix.policy.json"
           done

.github/workflows/verify-changesets.yml

@@ -54,7 +54,7 @@ jobs:
 
           if [ "${#changesets_changed[@]}" -gt 0 ]; then
             bun changeset status --since "$BASE_SHA" --output /tmp/changeset-status.json
-            bun scripts/verify-changesets.ts /tmp/changeset-status.json "${changesets_changed[@]}"
+            node scripts/verify-changesets.ts /tmp/changeset-status.json "${changesets_changed[@]}"
           fi
 
           if git diff --name-only "$BASE_SHA"...HEAD -- server/application/src/main/resources/db/changelog/ | grep -q .; then

AGENTS.md

@@ -18,9 +18,9 @@ and neither the application nor a review is an *agent*.
   See `webapp/AGENTS.md`.
 - `docs/` — contributor docs published to GitHub Pages, including the generated ERD.
 
-The repository uses Bun for JavaScript and TypeScript execution and package management;
-`package.json#packageManager` is the authoritative version. `webapp` is the main TypeScript
-package; `docs` is a second. The runner
+The repository uses Node.js for repository scripts and application tooling, and Bun for package
+management; `package.json#devEngines.runtime` and `packageManager` are the authoritative versions.
+`webapp` is the main TypeScript package; `docs` is a second. The runner
 (`server/application/src/main/resources/agent/`), the precompute runner and lib (`docker/agents/precompute/`) and
 the per-practice precompute scripts (`server/application/src/main/resources/practices/precompute/`) are
 type-checked as one project via `tsconfig.agents.json` and
@@ -77,7 +77,7 @@ checks, and security scans. Run `check` before pushing and `verify` before reque
 |---|---|---|---|
 | the SPA (`webapp/`) | `webapp/.oxlintrc.json` | oxfmt (`.oxfmtrc.json`) | `format:webapp`, `lint:webapp`, `check:webapp` |
 | the docs site (`docs/`) | `docs/.oxlintrc.json` | oxfmt for JavaScript, TypeScript, JSON/JSONC, and CSS (`.oxfmtrc.json`) | `format:docs`; linted by `lint:agents` |
-| the Bun agent runtime and specs, both precompute trees, and `scripts/**` | `.oxlintrc.json` | oxfmt (`.oxfmtrc.json`) | `format:agents`, `lint:agents`, `check:agents` |
+| the agent runtime and specs, both precompute trees, and `scripts/**` | `.oxlintrc.json` | oxfmt (`.oxfmtrc.json`) | `format:agents`, `lint:agents`, `check:agents` |
 | selected repository tooling configuration | `.oxlintrc.json` where applicable | oxfmt (`.oxfmtrc.json`) | `format:config` |
 
 `docs:lint` is **not** the oxlint leg — it is the docs package's own `typecheck` plus
@@ -105,8 +105,8 @@ adding a rule there enables it nowhere. `webapp/AGENTS.md` § Linting has the re
 Holds wherever TypeScript is written here, the Bun agent trees and `scripts/**` included.
 `webapp/AGENTS.md` wins over it inside the SPA.
 
-Prefer typed Bun/TypeScript for repository automation, validation, and tests. Keep shell only at a
-real runtime boundary where Bun is unavailable, such as an end-user bootstrap that must run before
+Prefer typed Node.js/TypeScript for repository automation, validation, and tests. Keep shell only at a
+real runtime boundary where Node.js is unavailable, such as an end-user bootstrap that must run before
 the application toolchain is installed; keep that boundary POSIX-compatible and move its substantive
 test orchestration into TypeScript.
 

CONTRIBUTING.md

@@ -2,6 +2,10 @@
 
 Read the [local development guide](https://ls1intum.github.io/Hephaestus/contributor/local-development) on how to set up your environment.
 
+Repository tooling requires the Node.js version pinned in `package.json#devEngines.runtime`. Bun
+installs dependencies and dispatches package scripts; TypeScript scripts and application tools execute
+on Node.js.
+
 ## Maintenance Status
 
 Hephaestus is a research project at TUM, actively developed but maintained primarily by one person. Issues and pull requests are triaged on a best-effort basis. Security reports are the exception and get priority — see [SECURITY.md](SECURITY.md) for how to report vulnerabilities privately.

INSTALL.md

@@ -8,3 +8,5 @@ There is exactly **one supported install**: the Docker Compose stack in
 
 For contributor/development setup, see the
 [contributor docs](https://ls1intum.github.io/Hephaestus/contributor/local-development) instead.
+Contributors need the Node.js and Bun versions pinned in `package.json`. The supported repository-based
+installation also uses the pinned Node.js version to verify signed release locks.

bunfig.toml

@@ -4,6 +4,3 @@ hoist = false
 publicHoistPattern = ["react", "react-dom", "@types/react", "@types/react-dom", "@types/hast"]
 minimumReleaseAge = 259200
 peer = true
-
-[run]
-bun = true

docs/admin/install.mdx

@@ -37,7 +37,7 @@ The stack you get:
 - Outbound HTTPS to `ghcr.io` and `docker.io` for images, `github.com` and `api.github.com` for the
   release lock, and `fulcio.sigstore.dev`, `rekor.sigstore.dev`, and `tuf-repo-cdn.sigstore.dev` for
   keyless signature verification.
-- The version of [Bun](https://bun.sh/docs/installation) pinned by `package.json`,
+- The [Node.js](https://nodejs.org/en/download) version pinned in `package.json#devEngines.runtime`,
   [GitHub CLI](https://cli.github.com/) authenticated with `gh auth login`, and
   [Cosign](https://docs.sigstore.dev/cosign/system_config/installation/) for release-lock verification.
 
@@ -55,7 +55,7 @@ cd /opt/hephaestus
 cd docker/self-host
 ./setup.sh
 cd ../..
-bun scripts/prepare-release-lock.ts "v$VERSION"
+node scripts/prepare-release-lock.ts "v$VERSION"
 cd docker/self-host
 ```
 
@@ -193,7 +193,7 @@ what a version number promises: [Compatibility Policy](./compatibility-policy).
 VERSION=<new version>
 cd /opt/hephaestus
 sudo git fetch --depth 1 origin tag "v$VERSION" && sudo git checkout "v$VERSION"
-bun scripts/prepare-release-lock.ts "v$VERSION"
+node scripts/prepare-release-lock.ts "v$VERSION"
 cd docker/self-host && docker compose --env-file .env --env-file release-lock.env pull && docker compose --env-file .env --env-file release-lock.env up -d
 ```
 
@@ -210,7 +210,7 @@ VERSION=<previous version>
 cd /opt/hephaestus
 sudo git fetch --depth 1 origin tag "v$VERSION"
 sudo git checkout "v$VERSION"
-bun scripts/prepare-release-lock.ts "v$VERSION"
+node scripts/prepare-release-lock.ts "v$VERSION"
 cd docker/self-host
 docker compose --env-file .env --env-file release-lock.env up -d --remove-orphans --wait
 ```

docs/contributor/local-development.mdx

@@ -14,9 +14,11 @@ Install and configure the following tools before you attempt a local build:
 1. **Java JDK 21** – Required for the Spring Boot application server.
 2. **Docker and Docker Compose** – Required for PostgreSQL and NATS. Verify both with `docker info`
    and `docker compose version`.
-3. **Bun** – Match `package.json#packageManager`; it runs JavaScript and TypeScript tooling and
-   installs dependencies. See [ADR 0033](https://github.com/ls1intum/Hephaestus/blob/main/docs/decisions/0033-bun-is-the-javascript-runtime-and-package-manager.md).
-4. **NATS CLI (optional)** – Helpful when inspecting the webhook/sync event stream (NATS is disabled by default locally). The agent job queue runs on PostgreSQL and needs no NATS.
+3. **Node.js** – Match `package.json#devEngines.runtime`; it executes repository scripts and
+   application tooling.
+4. **Bun** – Match `package.json#packageManager`; it installs dependencies and dispatches package
+   scripts through `bun run`.
+5. **NATS CLI (optional)** – Helpful when inspecting the webhook/sync event stream (NATS is disabled by default locally). The agent job queue runs on PostgreSQL and needs no NATS.
 
 ## Recommended IDE setup
 

docs/package.json

@@ -3,16 +3,16 @@
 	"version": "0.0.0",
 	"private": true,
 	"scripts": {
-		"start": "bun --bun docusaurus start --no-open",
-		"build": "bun --bun docusaurus build",
-		"swizzle": "bun --bun docusaurus swizzle",
-		"deploy": "bun --bun docusaurus deploy",
-		"clear": "bun --bun docusaurus clear",
-		"serve": "bun --bun docusaurus serve",
-		"write-translations": "bun --bun docusaurus write-translations",
-		"write-heading-ids": "bun --bun docusaurus write-heading-ids",
-		"typecheck": "bun --bun tsc --noEmit",
-		"lint:md": "bun --bun markdownlint-cli2",
+		"start": "docusaurus start --no-open",
+		"build": "docusaurus build",
+		"swizzle": "docusaurus swizzle",
+		"deploy": "docusaurus deploy",
+		"clear": "docusaurus clear",
+		"serve": "docusaurus serve",
+		"write-translations": "docusaurus write-translations",
+		"write-heading-ids": "docusaurus write-heading-ids",
+		"typecheck": "tsc --noEmit",
+		"lint:md": "markdownlint-cli2",
 		"lint": "bun run typecheck && bun run lint:md"
 	},
 	"dependencies": {

jean.json

@@ -1,6 +1,6 @@
 {
 	"scripts": {
-		"setup": "bun \"$JEAN_ROOT_PATH/scripts/jean-setup.ts\"",
-		"run": "bun ./scripts/jean-public-test.ts start"
+		"setup": "node \"$JEAN_ROOT_PATH/scripts/jean-setup.ts\"",
+		"run": "node ./scripts/jean-public-test.ts start"
 	}
 }