Convert `yarn` to `bun`

[tyler-dane]

Feature Description

No response

Use Case

This'll save devs time while building, testing, etc

Additional Context

No response

[tyler-dane]

Full Bun-Native Toolchain Migration

Summary

The repo has already completed the first-stage migration to Bun as the package manager and script entrypoint layer. The next phase is Option C: full Bun-native toolchain migration.

That means moving beyond:

• Bun for install
• Bun for run / bunx
• Node/Jest/webpack still doing most of the actual work

And toward:

• Bun as package manager
• Bun as runtime for local/dev/CLI flows
• Bun-native testing where practical
• intentional removal of Node-era script runners and package-manager assumptions

Goal

Make Bun the default and primary tool across the monorepo, while preserving current app behavior.

Success means:

• the repo installs with Bun
• dev commands run through Bun-native execution
• CLI flows run through Bun-native execution
• test/build tooling is either Bun-native or intentionally retained with explicit justification
• obsolete Yarn and Node-era runner glue is removed
• docs and CI reflect the final Bun-native setup

Current State

Already done:

• bun install is the authoritative install flow
• bun.lock is checked in
• CI and Husky use Bun commands
• tracked Yarn config/lock artifacts were removed
• docs now point to Bun commands

Not yet Bun-native:

• backend dev flow still relies on node + ts-node-dev
• CLI still relies on node + ts-node/register
• web dev/build still relies on webpack binaries
• tests still rely on Jest and Playwright
• some dependency compatibility issues had to be patched during the package-manager migration

Scope

This issue covers the full Bun-native migration of the repo toolchain.

In scope:

• runtime execution for dev and CLI flows
• unit/integration test strategy
• build/dev script modernization
• CI updates needed for Bun-native tooling
• dependency cleanup after migration
• docs updates for final workflow

Out of scope unless explicitly needed:

• product behavior changes
• backend API changes
• frontend feature work
• schema or data model changes

Migration Strategy

Phase 1: Stabilize the Bun dependency graph

Before replacing more tooling, stabilize the current install so the repo has a predictable baseline.

• Audit major package-version drift introduced by Bun resolution
• Pin toolchain dependencies that must stay on known-good versions
• Add explicit overrides where Bun resolution breaks runtime/tooling behavior
• Re-run lockfile generation from a clean checkout on macOS and Linux
• Confirm bun install produces a reproducible working install

Focus areas:

• TypeScript
• Jest ecosystem packages
• Playwright
• ESLint stack
• webpack/tooling packages
• Rushstack / Umzug CLI transitive dependencies
• Node typings

Phase 2: Migrate runtime execution from Node wrappers to Bun

Backend dev flow

Current state:

• root script shells into node + ts-node-dev

Target state:

• backend dev server runs through Bun-native TypeScript execution and watch mode

Tasks:

• Replace ts-node-dev flow with Bun-based execution
• Preserve current env-file loading behavior
• Preserve restart/watch ergonomics
• Verify source maps and stack traces are acceptable
• Remove ts-node-dev if no longer needed

CLI flow

Current state:

• root CLI script uses node --env-file ... -r ts-node/register/transpile-only -r tsconfig-paths/register

Target state:

• CLI runs directly through Bun

Tasks:

• Run the CLI entrypoint with Bun-native TS execution
• Replace Node preload-based path alias handling if needed
• Verify Commander + Umzug flows under Bun
• Verify migrations/seeders/delete/build commands under Bun
• Remove ts-node if no longer needed

Phase 3: Decide the web build/dev end-state

The repo currently uses webpack directly. This phase needs an explicit decision.

Option 1: Keep webpack, make Bun the runtime wrapper

This is the lower-risk path.

• Keep webpack as the bundler
• Ensure dev/build commands invoke webpack through Bun-native entrypoints cleanly
• Remove unnecessary Node-era wrapper assumptions

Option 2: Replace webpack with a Bun-native build strategy

This is the larger path.

• Evaluate Bun build compatibility with current app needs
• Audit requirements: React app, env injection, HTML output, asset handling, test setup, dev server behavior
• Decide whether Bun can fully replace webpack without regressions
• If yes, create a dedicated migration issue/plan for bundler replacement

Recommended default: keep webpack unless there is a strong reason to replace it now.

Phase 4: Migrate tests toward Bun-native tooling

This is the largest and riskiest part of Option C.

Unit and integration tests

Current state:

• Jest projects for core, web, backend, scripts

Target state:

• Bun-native test execution where practical, or an explicitly hybrid model if full parity is not realistic

Tasks:

• Audit all Jest-specific features currently used:
  • project config
  • mocks/spies
  • jsdom setup
  • setup files
  • Mongo test environment
  • snapshots if any
• Prototype core migration to bun test
• Prototype web migration and validate Testing Library compatibility
• Prototype backend/scripts migration, especially Mongo test setup
• Decide whether full Jest replacement is practical
• If not, document the final hybrid strategy explicitly

Recommended sequencing:

1. core
2. web
3. scripts
4. backend

End-to-end tests

Current state:

• Playwright

Target state:

• either keep Playwright intentionally or replace it only if Bun adds real value

Tasks:

• Keep Playwright unless there is a strong migration benefit
• Ensure Playwright bootstraps cleanly from the Bun-native dev/build flow
• Update CI and docs for final e2e invocation model

Recommended default: keep Playwright.

Phase 5: Clean up obsolete dependencies and scripts

After the runtime/tooling migration is complete:

• Remove ts-node
• Remove ts-node-dev
• Remove tsconfig-paths/register usage if no longer needed
• Remove package-manager-specific workarounds that no longer apply
• Remove Bun migration compatibility pins that are no longer necessary
• Simplify root scripts to reflect the final Bun-native flow

Phase 6: CI and docs finalization

• Update CI to reflect the final Bun-native runtime/test/build model
• Update README.md
• Update AGENTS.md
• Update CONTRIBUTING.md
• Update .cursorrules
• Update docs/ command references and workflow docs
• Document any intentionally retained non-Bun tooling

Validation Plan

Required validation

• bun install
• bun run dev:web
• bun run dev:backend
• bun run cli --help
• bun run cli build web --environment staging --clientId "test-client-id"
• bun run cli build nodePckgs --environment staging
• final unit/integration test commands pass
• e2e passes
• bun run type-check
• ESLint passes on migrated implementation files

Environment notes

Some checks require a normal local or CI environment, not a restricted sandbox:

• backend/scripts tests need local port binding for mongodb-memory-server
• e2e needs browser/runtime support
• backend dev validation needs a valid .env.local

Acceptance Criteria

• Bun is the primary install, runtime, and tooling entrypoint across the repo
• No root script depends on ts-node or ts-node-dev
• CLI runs without Node preload hooks
• Final test strategy is Bun-native or explicitly hybrid with documented reasons
• Remaining webpack/Playwright usage is intentional and documented
• bun install and bun.lock are stable and reproducible
• Docs describe the final Bun-native workflow
• No tracked Yarn-era config or command references remain
• No unnecessary Node-runner glue remains

Risks

• Bun lockfile generation can drift transitive versions unless pinned intentionally
• Jest replacement may be expensive because the repo uses multi-project config and custom setup layers
• backend/scripts tests depend on Mongo in-memory infrastructure, which may complicate Bun-native migration
• webpack replacement may expand scope significantly if attempted in the same issue
• trying to replace runtime, bundler, and test tooling all at once may create a large debugging surface

Recommended Breakdown

This should probably be implemented as an umbrella issue with sub-issues:

1. Stabilize Bun dependency graph
2. Migrate backend dev runtime to Bun
3. Migrate CLI runtime to Bun
4. Decide web bundler strategy
5. Prototype Bun-native tests for core
6. Migrate web tests
7. Migrate scripts and backend tests
8. Final CI/docs/dependency cleanup

Recommended Next Step

Start with:

1. stabilizing the Bun dependency graph
2. migrating the CLI and backend dev runtime to Bun
3. deferring Jest/webpack replacement until those runtime flows are stable

That keeps the migration incremental while still moving decisively toward a full Bun-native repo.