Adopt Bun for install + script running (selective migration)

Package manager is now Bun: bun install replaces npm install, bun run <script>
replaces npm run <script>, and the committed lockfile is bun.lock (migrated
from package-lock.json). Install drops from ~90s to ~5s locally.

Deliberately selective, not a full stack swap. Two parallel research agents
came back with:

- tests/.../research-bun-test-migration.md: bun test has multiple blockers
  for this repo — vi.resetModules() unimplemented (oven-sh/bun#16140, open
  as of 2026-07), vi.mock() not hoisted (needs preload/await import()
  refactor), coverage emits lcov only (no Istanbul JSON, which our
  scripts/merge-coverage.mjs consumes), fake timers missing. Rough effort
  estimate 15–30 hrs, dominated by module-mock refactors, for the single
  feature we cared about (per-file coverage threshold) which Vitest already
  provides via coverage.thresholds.perFile. Staying on Vitest.

- tests/.../research-bun-runtime-compat.md: Miniflare's workerd child-process
  lifecycle is the biggest risk switching to Bun as the top-level runtime;
  Playwright + Bun is known-flaky (microsoft/playwright#27139); Wrangler +
  Bun is officially documented; Vite 7 + @cloudflare/vite-plugin works for
  builds, less so for dev. Recommendation was a selective switch matching
  what this commit does.

Smoke-tested locally under bun run:
 - bun run test:unit:        20 files, 388 tests, all pass
 - bun run test:integration: 7 files,  70 tests, all pass
 - bun run test:e2e:         49 tests, all pass
 - bun run lint / typecheck / build: clean

CI changes (.github/workflows/ci.yml):
 - Every job replaces actions/setup-node@v4 + npm ci with oven-sh/setup-bun@v2
   + bun install --frozen-lockfile.
 - Scripts invoked via bun run.
 - The e2e + visual jobs keep actions/setup-node@v4 alongside setup-bun so
   Playwright's test runner has a clean Node host for its browser worker
   subprocesses — and those jobs explicitly call `npx playwright test`
   instead of `bun run test:e2e` to route around playwright#27139.
 - bun_version pinned to 1.3.11 to match the local smoke-tested version.

CLAUDE.md: documents the bun install / bun run convention and the reason
bun test migration is deferred.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: audreyt

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  NODE_VERSION: '22'
+  BUN_VERSION: '1.3.11'
 
 jobs:
   static:
@@ -19,27 +19,25 @@ jobs:
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: oven-sh/setup-bun@v2
         with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-      - run: npm ci --prefer-offline --no-audit --no-fund
-      - run: npm run lint
-      - run: npx tsc -b --noEmit
-      - run: npm run build
+          bun-version: ${{ env.BUN_VERSION }}
+      - run: bun install --frozen-lockfile
+      - run: bun run lint
+      - run: bun run typecheck
+      - run: bun run build
 
   unit:
     name: Unit tests (vitest)
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: oven-sh/setup-bun@v2
         with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-      - run: npm ci --prefer-offline --no-audit --no-fund
-      - run: npm run test:unit -- --reporter=default --reporter=junit --outputFile=unit-report.xml
+          bun-version: ${{ env.BUN_VERSION }}
+      - run: bun install --frozen-lockfile
+      - run: bun run test:unit -- --reporter=default --reporter=junit --outputFile=unit-report.xml
       - name: Upload unit report
         if: always()
         uses: actions/upload-artifact@v4
@@ -54,12 +52,11 @@ jobs:
     timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: oven-sh/setup-bun@v2
         with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-      - run: npm ci --prefer-offline --no-audit --no-fund
-      - run: npm run test:integration
+          bun-version: ${{ env.BUN_VERSION }}
+      - run: bun install --frozen-lockfile
+      - run: bun run test:integration
 
   e2e:
     name: E2E (playwright chromium)
@@ -69,11 +66,16 @@ jobs:
       E2E_SKIP_BUILD: '1'
     steps:
       - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+      # Node stays installed alongside Bun so Playwright's test runner
+      # (known-flaky under Bun per microsoft/playwright#27139) has a clean
+      # subprocess host for its browser workers.
       - uses: actions/setup-node@v4
         with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-      - run: npm ci --prefer-offline --no-audit --no-fund
+          node-version: '22'
+      - run: bun install --frozen-lockfile
       - name: Get Playwright version
         id: pw
         run: echo "version=$(node -p "require('@playwright/test/package.json').version")" >> "$GITHUB_OUTPUT"
@@ -89,8 +91,8 @@ jobs:
       - name: Install Playwright OS deps (for cached browsers)
         if: steps.pw-cache.outputs.cache-hit == 'true'
         run: npx playwright install-deps chromium
-      - run: npm run build
-      - run: npm run test:e2e
+      - run: bun run build
+      - run: npx playwright test --project=chromium
       - name: Upload Playwright report
         if: always()
         uses: actions/upload-artifact@v4
@@ -115,11 +117,13 @@ jobs:
       E2E_SKIP_BUILD: '1'
     steps:
       - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
       - uses: actions/setup-node@v4
         with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: npm
-      - run: npm ci --prefer-offline --no-audit --no-fund
+          node-version: '22'
+      - run: bun install --frozen-lockfile
       - name: Check if linux baselines exist
         id: baselines
         run: |
@@ -131,9 +135,9 @@ jobs:
       - name: Install Playwright
         if: steps.baselines.outputs.exist == 'true'
         run: npx playwright install --with-deps chromium
-      - run: npm run build
+      - run: bun run build
         if: steps.baselines.outputs.exist == 'true'
-      - run: npm run test:e2e:visual
+      - run: npx playwright test --project=visual
         if: steps.baselines.outputs.exist == 'true'
       - name: Upload visual diff report
         if: always() && steps.baselines.outputs.exist == 'true'

CLAUDE.md

@@ -28,20 +28,27 @@ commands/         # 上傳腳本（upload_dictionary.sh、upload_assets.sh）
 
 ## 常用指令
 
+Package manager is **Bun** (`bun install`, `bun run <script>`). Lockfile is `bun.lock`. Anything
+that used to be `npm run X` now runs as `bun run X`; `npm install` still works if needed for
+tooling that doesn't understand `bun.lock`, but CI and the documented flow use Bun.
+
 ```bash
-npm run dev       # 本地開發
-npm run build     # 建置
-npm run deploy    # 建置並部署至 Cloudflare
-npm run lint      # ESLint 檢查
-npm run typecheck # tsc -b --noEmit
-
-# Tests (three tiers)
-npm run test:unit          # Vitest + happy-dom (src/utils, src/ssr, src/api)
-npm run test:integration   # Miniflare-backed worker API tests (hermetic, seeded from data/dictionary/)
-npm run test:e2e           # Playwright browser tests (excludes visual regression)
-npm run test:e2e:visual    # Playwright visual regression (baselines per-OS)
-npm run test:e2e:update    # Regenerate Playwright snapshots for current platform
-npm run test               # Run all three tiers sequentially
+bun install       # install dependencies (replaces npm install)
+bun run dev       # 本地開發
+bun run build     # 建置
+bun run deploy    # 建置並部署至 Cloudflare
+bun run lint      # ESLint 檢查
+bun run typecheck # tsc -b --noEmit
+
+# Tests (three tiers) — runner is still Vitest + Playwright under the hood;
+# Bun is just the script host. `bun test` migration is blocked on oven-sh/bun#16140
+# (`vi.resetModules` missing), so stay on Vitest for now.
+bun run test:unit          # Vitest + happy-dom (src/utils, src/ssr, src/api, worker)
+bun run test:integration   # Miniflare-backed worker API tests (hermetic, seeded from data/dictionary/)
+bun run test:e2e           # Playwright browser tests (excludes visual regression)
+bun run test:e2e:visual    # Playwright visual regression (baselines per-OS)
+bun run test:e2e:update    # Regenerate Playwright snapshots for current platform
+bun run test               # Run all three tiers sequentially
 ```
 
 ### Visual regression baselines