Refine build pipeline error handling and cache docs

Use CPU count to cap default thread workers and simplify
webpack error checks. Ensure watch-once packaging failures
surface as non-zero exits. Key CI webpack cache by full
Node version. Clarify cache compression behavior in
AGENTS documentation.

Author: PeterDaveHello

.github/workflows/pre-release-build.yml

@@ -26,18 +26,18 @@ jobs:
           node-version: 20
           cache: 'npm'
           cache-dependency-path: '**/package-lock.json'
-      - name: Detect Node major version
-        run: echo "NODE_MAJOR=$(node -p 'process.versions.node.split(".")[0]')" >> $GITHUB_ENV
+      - name: Detect Node version
+        run: echo "NODE_VERSION=$(node -p 'process.versions.node')" >> $GITHUB_ENV
       - run: npm ci
       - name: Cache Webpack filesystem cache
         uses: actions/cache@v4
         with:
           path: |
             .cache/webpack
             node_modules/.cache/webpack
-          key: ${{ runner.os }}-node${{ env.NODE_MAJOR }}-webpack-${{ hashFiles('**/package-lock.json', 'build.mjs') }}
+          key: ${{ runner.os }}-node${{ env.NODE_VERSION }}-webpack-${{ hashFiles('**/package-lock.json', 'build.mjs') }}
           restore-keys: |
-            ${{ runner.os }}-node${{ env.NODE_MAJOR }}-webpack-
+            ${{ runner.os }}-node${{ env.NODE_VERSION }}-webpack-
       - run: npm run build
 
       - uses: josStorer/get-current-time@v2

AGENTS.md

@@ -28,6 +28,7 @@ Always reference these instructions first and fall back to search or bash comman
   - Default: `0` (no compression) for faster warm builds on CPU-bound SSD machines
   - Options: `0|false|none`, `gzip` (or `brotli` if explicitly desired)
   - Affects only `.cache/webpack` size/speed; does not change final artifacts
+  - Note: Babel loader cache uses its own compression setting (currently disabled for speed) and is independent of BUILD_CACHE_COMPRESSION
 - BUILD_WATCH_ONCE (dev): When set, `npm run dev` runs a single build and exits (useful for timing)
 - BUILD_POOL_TIMEOUT: Override thread-loader production pool timeout (ms)
   - Default: `2000`. Increase if workers recycle too aggressively on slow machines/CI

build.mjs

@@ -55,7 +55,7 @@ try {
   cpuCount = 1
 }
 function parseThreadWorkerCount(envValue, cpuCount) {
-  const maxWorkers = Math.max(1, cpuCount - 1)
+  const maxWorkers = Math.max(1, cpuCount)
   if (envValue !== undefined && envValue !== null) {
     const rawStr = String(envValue).trim()
     if (/^[1-9]\d*$/.test(rawStr)) {
@@ -413,10 +413,7 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
   if (isProduction) {
     // Ensure compiler is properly closed after production runs
     compiler.run((err, stats) => {
-      const hasErrors = !!(
-        err ||
-        (stats && typeof stats.hasErrors === 'function' && stats.hasErrors())
-      )
+      const hasErrors = !!(err || stats?.hasErrors?.())
       let callbackFailed = false
       const finishClose = () =>
         compiler.close((closeErr) => {
@@ -445,10 +442,7 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
     })
   } else {
     const watching = compiler.watch({}, (err, stats) => {
-      const hasErrors = !!(
-        err ||
-        (stats && typeof stats.hasErrors === 'function' && stats.hasErrors())
-      )
+      const hasErrors = !!(err || stats?.hasErrors?.())
       // Normalize callback return into a Promise to catch synchronous throws
       const ret = Promise.resolve().then(() => callback(err, stats))
       if (isWatchOnce) {
@@ -626,7 +620,7 @@ async function build() {
         minimal,
         tmpDir,
         async (err, stats) => {
-          if (err || (stats && typeof stats.hasErrors === 'function' && stats.hasErrors())) {
+          if (err || stats?.hasErrors?.()) {
             console.error(err || stats.toString())
             reject(err || new Error('webpack error'))
             return
@@ -665,10 +659,7 @@ async function build() {
 
   await new Promise((resolve, reject) => {
     const ret = runWebpack(false, false, false, outdir, async (err, stats) => {
-      const hasErrors = !!(
-        err ||
-        (stats && typeof stats.hasErrors === 'function' && stats.hasErrors())
-      )
+      const hasErrors = !!(err || stats?.hasErrors?.())
       if (hasErrors) {
         console.error(err || stats.toString())
         // In normal dev watch, keep process alive on initial errors; only fail when watch-once
@@ -683,6 +674,10 @@ async function build() {
       } catch (e) {
         // Packaging failure should stop even in dev to avoid silent success
         reject(e)
+        if (isWatchOnce) {
+          // Re-throw to surface an error and exit non-zero even if rejection isn't awaited
+          throw e
+        }
       }
     })
     // Early setup failures (e.g., dynamic imports) should fail fast