feat: add comprehensive Bun package manager support (#257)

* feat: add comprehensive Bun package manager support

     This commit introduces full Bun package manager integration to the CircleCI Node orb,
     adding Bun as a first-class supported package manager alongside npm, yarn, yarn-berry, and pnpm.

     ## Core Installation Infrastructure
     - Add install-bun command with version management and retry logic
     - Add Bun installation script with automatic version detection
     - Integrate bun-version parameter into main install command
     - Support for both specific versions and latest stable releases

     ## Package Management Integration
     - Add 'bun' to pkg-manager enum across all commands and jobs
     - Implement bun-install.sh with frozen lockfile default for reproducible builds
     - Add support for both bun.lock (text) and bun.lockb (binary) lockfiles
     - Configure cache support via BUN_INSTALL_CACHE_DIR environment variable
     - Default cache path: ~/.bun/install/cache with override capability

     ## Job Execution Support
     - Add bun-run parameter to run job for script execution
     - Integrate Bun command execution in run-commands-with.sh
     - Add Bun test runner support with native JUnit XML output
     - Support Jest and Mocha test frameworks via Bun's built-in test runner

     ## Testing & CI Integration
     - Add comprehensive integration tests for all Bun functionality:
       - Installation (specific versions and latest)
       - Package installation with caching
       - Test execution (Jest/Mocha compatibility)
       - Script execution via bun run
       - Cross-platform support (Linux, macOS, machine)
       - Multi-architecture support (ARM64, x86_64)

     ## Documentation & Examples
     - Create three example configurations:
       - bun_install.yml: Basic Bun installation and package management
       - node_bun_run.yml: Script execution with Bun
       - run_tests_with_bun.yml: Test runner integration
     - Update orb description to include Bun in supported package managers

     ## Key Features & Benefits
     - Frozen lockfile by default (--frozen-lockfile) ensures reproducible builds
     - Network retry logic (--retry 5) for robust CI installations
     - Native test runner with built-in JUnit XML output (no additional dependencies)
     - Automatic lockfile detection for both text (.lock) and binary (.lockb) formats
     - Seamless integration with existing orb caching mechanisms
     - Full compatibility with CircleCI's artifact and test result collection

     This enhancement maintains backward compatibility while extending the orb's
     package manager support to include Bun's fast JavaScript runtime and toolkit.
     The implementation follows existing patterns for consistency and includes
     comprehensive test coverage across all supported platforms and architectures.

* fix: replace GitHub API call with redirect method for Bun version detection

Replace api.github.com usage with github.com redirect approach to avoid
rate limiting issues. This follows the same pattern used for other tools
in the orb (e.g., Dockerize).

Changed from parsing JSON API response to extracting version from the
redirect URL of the releases/latest endpoint.

* Add new line at the end

* fix: address typo in path segment that blocked bun installation

* Add new line at the end

* fix: remove integration-test-install-bun-latest job from workflow

The job definition was deleted but references to it remained in the workflow,
causing CI failures. This removes the job from both the workflow jobs list
and the orb publish requirements.

* chore: update Bun version from 1.2.21 to 1.2.22

Updates all references to Bun version 1.2.21 to use version 1.2.22 across:
- CI test configurations in .circleci/test-deploy.yml
- Documentation examples in src/examples/

* fix: correct Bun test runner integration

- Fix Bun+Jest to run Jest via 'bun run' instead of native 'bun test'
- Fix Bun+Mocha to check dependencies properly
- Add 'bun' as test-results-for option for native Bun test runner
- Add examples showing both native and Jest/Mocha usage

* fix: add automatic test result collection for native Bun tests

* improve: simplify Bun cache configuration and add lockfile warnings

- Remove explicit cache-path from examples (orb defaults work correctly)
- Add warning when both bun.lock and bun.lockb are present
- Set explicit BUN_INSTALL_CACHE_DIR default for consistency
- Clarify in examples that cache path is automatically configured

* fix: use npm global install for Bun to ensure PATH availability

Switch from Bun's official installer to npm global install method,
following the same pattern as pnpm. This ensures Bun is properly
available in PATH for subsequent CircleCI steps without requiring
manual PATH manipulation or BASH_ENV exports.

* test: add Bun native test runner coverage and lockfile consistency

Completes the Bun integration by adding test coverage for Bun's native
test runner and ensuring lockfile handling consistency across all package
managers.

Changes:
- Add node-bun-native-test-job to test Bun's built-in test runner with
  JUnit output verification
- Create minimal test file at sample/bun-tests/simple.test.js for native
  test runner validation
- Generate and commit bun.lock file to match the pattern of having all
  package manager lockfiles in the repository
- Update non-Bun package manager tests to remove bun.lock, ensuring
  clean test isolation

* Fix linter

* fix: patch sec vulnerability

* fix: resolve Bun test runner issues in CircleCI orb

- Fix Jest/Bun haste map collisions by adding modulePathIgnorePatterns to exclude Bun cache
- Fix Bun native test runner by specifying bun-tests directory for test discovery

These changes address pipeline failures in the node-bun-jest-test-job and
node-bun-native-test-job by preventing Jest from scanning Bun's package
cache and ensuring the native runner finds test files correctly.

* update lock files

* fix: resolve Bun test runner issues in CircleCI orb

- Fix Bun native test runner to output JUnit results to junit.xml
- Fix Bun + Jest mode to look for results at junit.xml instead of test-results
- Add test case for Bun native runner with custom test-results-path
- Remove incorrect post_install_steps verification from Bun native test job

* fix: linter errors, rm trailing spaces

---------

Co-authored-by: Mateo Arboleda <[email protected]>

Author: synapseradio

.circleci/test-deploy.yml

@@ -64,6 +64,23 @@ jobs:
               echo "pnpm version 9.7.1 not found"
               exit 1
             fi
+  integration-test-install-bun-specified:
+    parameters:
+      os:
+        type: executor
+    executor: <<parameters.os>>
+    steps:
+      - checkout
+      - node/install:
+          nvm-cache-key: v2
+      - node/install-bun:
+          version: "1.2.22"
+      - run:
+          command: |
+            if ! bun --version | grep -q "1.2.22"; then
+              echo "Bun version 1.2.22 not found"
+              exit 1
+            fi
   integration-test-reinstall-yarn:
     machine:
       image: ubuntu-2004:current
@@ -95,7 +112,7 @@ jobs:
     docker:
       - image: cimg/ruby:3.3.5-browsers
     steps:
-      - node/install: 
+      - node/install:
           install-yarn: true
           node-version: '22.11.0'
 
@@ -192,13 +209,43 @@ jobs:
           command: |
             rm ~/project/sample/package-lock.json
             rm ~/project/sample/yarn.lock
+            rm ~/project/sample/bun.lock
       - node/install-pnpm:
           version: "9.12.3"
       - node/install-packages:
           pkg-manager: pnpm
           cache-version: pnpm-v1
           app-dir: "~/project/sample"
       - run: cd ~/project/sample && pnpm test
+  integration-test-bun:
+    parameters:
+      resource_class:
+        type: enum
+        default: medium
+        description: Configure the executor resource class
+        enum:
+            - medium
+            - arm.medium
+    executor:
+      name: node/default
+      resource_class: <<parameters.resource_class>>
+    steps:
+      - checkout
+      - run:
+          name: Remove other lock files and create bun lockfile
+          command: |
+            rm ~/project/sample/package-lock.json
+            rm ~/project/sample/yarn.lock
+            rm ~/project/sample/pnpm-lock.yaml
+            rm ~/project/sample/yarn-berry.lock
+      - node/install-bun:
+          version: "1.2.22"
+      - node/install-packages:
+          pkg-manager: bun
+          cache-path: ~/.bun/install/cache
+          cache-version: bun-v1
+          app-dir: "~/project/sample"
+      - run: cd ~/project/sample && bun test
   integration-test-yarn:
     parameters:
       resource_class:
@@ -274,6 +321,11 @@ workflows:
           matrix:
             parameters:
               os: [ linux, macos, machine ]
+      - integration-test-install-bun-specified:
+          filters: *filters
+          matrix:
+            parameters:
+              os: [ linux, macos, machine ]
       - integration-test-install-latest:
           filters: *filters
           matrix:
@@ -297,6 +349,7 @@ workflows:
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn.lock
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/test:
           filters: *filters
           name: node-yarn-jest-test-job
@@ -311,6 +364,7 @@ workflows:
                   rm ~/project/sample/package-lock.json
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/test:
           filters: *filters
           name: node-pnpm-jest-test-job
@@ -325,6 +379,7 @@ workflows:
                   rm ~/project/sample/package-lock.json
                   rm ~/project/sample/yarn.lock
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/test:
           filters: *filters
           name: node-npm-mocha-test-job
@@ -339,6 +394,7 @@ workflows:
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn.lock
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/test:
           filters: *filters
           name: node-yarn-mocha-test-job
@@ -354,6 +410,7 @@ workflows:
                   rm ~/project/sample/package-lock.json
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/test:
           filters: *filters
           name: node-yarn-berry-mocha-test-job
@@ -369,6 +426,7 @@ workflows:
                   rm ~/project/sample/package-lock.json
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn.lock
+                  rm ~/project/sample/bun.lock
                   rm ~/project/sample/package.json
                   mv ~/project/sample/yarn-berry.lock ~/project/sample/yarn.lock
                   mv ~/project/sample/package-berry.json ~/project/sample/package.json
@@ -387,6 +445,81 @@ workflows:
                   rm ~/project/sample/package-lock.json
                   rm ~/project/sample/yarn.lock
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
+      - node/test:
+          filters: *filters
+          name: node-bun-jest-test-job
+          app-dir: "~/project/sample"
+          cache-version: v2
+          test-results-for: jest
+          pkg-manager: bun
+          cache-path: ~/.bun/install/cache
+          setup:
+            - node/install-bun:
+                version: "1.2.22"
+            - run:
+                name: Remove other lock files
+                command: |
+                  rm ~/project/sample/package-lock.json
+                  rm ~/project/sample/yarn.lock
+                  rm ~/project/sample/pnpm-lock.yaml
+                  rm ~/project/sample/yarn-berry.lock
+      - node/test:
+          filters: *filters
+          name: node-bun-mocha-test-job
+          app-dir: "~/project/sample"
+          cache-version: v2
+          test-results-for: mocha
+          pkg-manager: bun
+          cache-path: ~/.bun/install/cache
+          run-command: testmocha
+          setup:
+            - node/install-bun:
+                version: "1.2.22"
+            - run:
+                name: Remove other lock files
+                command: |
+                  rm ~/project/sample/package-lock.json
+                  rm ~/project/sample/yarn.lock
+                  rm ~/project/sample/pnpm-lock.yaml
+                  rm ~/project/sample/yarn-berry.lock
+      - node/test:
+          filters: *filters
+          name: node-bun-native-test-job
+          app-dir: "~/project/sample"
+          cache-version: v2
+          test-results-for: bun
+          pkg-manager: bun
+          cache-path: ~/.bun/install/cache
+          setup:
+            - node/install-bun:
+                version: "1.2.22"
+            - run:
+                name: Remove other lock files
+                command: |
+                  rm ~/project/sample/package-lock.json
+                  rm ~/project/sample/yarn.lock
+                  rm ~/project/sample/pnpm-lock.yaml
+                  rm ~/project/sample/yarn-berry.lock
+      - node/test:
+          filters: *filters
+          name: node-bun-native-with-test-result-path-job
+          app-dir: "~/project/sample"
+          cache-version: v2
+          test-results-for: bun
+          pkg-manager: bun
+          cache-path: ~/.bun/install/cache
+          test-results-path: sample/bun-junit.xml
+          setup:
+            - node/install-bun:
+                version: "1.2.22"
+            - run:
+                name: Remove other lock files
+                command: |
+                  rm ~/project/sample/package-lock.json
+                  rm ~/project/sample/yarn.lock
+                  rm ~/project/sample/pnpm-lock.yaml
+                  rm ~/project/sample/yarn-berry.lock
       - node/test:
           filters: *filters
           name: node-yarn-mocha-with-test-result-path-job
@@ -403,6 +536,7 @@ workflows:
                   rm ~/project/sample/package-lock.json
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/test:
           filters: *filters
           name: node-test-results-file-job
@@ -416,6 +550,7 @@ workflows:
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn.lock
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/test:
           filters: *filters
           name: node-test-no-junit
@@ -428,6 +563,7 @@ workflows:
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn.lock
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/test:
           filters: *filters
           name: node-test-no-junit-new-features
@@ -445,6 +581,7 @@ workflows:
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn.lock
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/test:
           filters: *filters
           name: node-test-with-coverage
@@ -465,6 +602,7 @@ workflows:
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn.lock
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/run:
           filters: *filters
           name: node-run-yarn-job
@@ -479,6 +617,7 @@ workflows:
                   rm ~/project/sample/package-lock.json
                   rm ~/project/sample/pnpm-lock.yaml
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
       - node/run:
           filters: *filters
           name: node-run-upload-artifacts
@@ -500,6 +639,25 @@ workflows:
                   rm ~/project/sample/package-lock.json
                   rm ~/project/sample/yarn.lock
                   rm ~/project/sample/yarn-berry.lock
+                  rm ~/project/sample/bun.lock
+      - node/run:
+          filters: *filters
+          name: node-run-bun-job
+          app-dir: "~/project/sample"
+          cache-version: v3
+          pkg-manager: bun
+          bun-run: build
+          cache-path: ~/.bun/install/cache
+          setup:
+            - node/install-bun:
+                version: "1.2.22"
+            - run:
+                name: Remove other lock files
+                command: |
+                  rm ~/project/sample/package-lock.json
+                  rm ~/project/sample/yarn.lock
+                  rm ~/project/sample/pnpm-lock.yaml
+                  rm ~/project/sample/yarn-berry.lock
       - integration-test-override-ci:
           matrix:
             alias: integration-test-override-ci
@@ -512,6 +670,12 @@ workflows:
             parameters:
               resource_class: [arm.medium, medium]
           filters: *filters
+      - integration-test-bun:
+          matrix:
+            alias: integration-test-bun
+            parameters:
+              resource_class: [arm.medium, medium]
+          filters: *filters
       - integration-test-override-ci-windows:
           filters: *filters
       - integration-test-yarn:
@@ -545,9 +709,12 @@ workflows:
             - integration-test-install-latest
             - integration-test-install-lts
             - integration-test-install-pnpm
+            - integration-test-install-bun-specified
             - integration-test-pnpm
+            - integration-test-bun
             - integration-test-reinstall-yarn
             - node-yarn-mocha-with-test-result-path-job
+            - node-bun-native-with-test-result-path-job
             - integration-test-override-yarn
             - node-yarn-mocha-test-job
             - node-yarn-jest-test-job
@@ -556,10 +723,14 @@ workflows:
             - node-test-with-coverage
             - node-run-npm-job
             - node-pnpm-mocha-test-job
+            - node-bun-jest-test-job
+            - node-bun-mocha-test-job
+            - node-bun-native-test-job
             - node-test-no-junit
             - node-pnpm-jest-test-job
             - node-run-yarn-job
             - node-run-pnpm-job
+            - node-run-bun-job
             - node-run-upload-artifacts
           github_token: GHI_TOKEN
           context: orb-publisher

sample/bun-tests/simple.test.js

@@ -0,0 +1,5 @@
+import { expect, test } from "bun:test";
+
+test("2 + 2", () => {
+  expect(2 + 2).toBe(4);
+});