Refine build helpers and CI cache docs

Document BUILD_RESOLVE_SYMLINKS and cache compression
behavior, and tighten related parsing in the build script.
Ensure watch-once packaging failures exit non-zero and
simplify error logging.
Key CI webpack cache by full Node version for safety.

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,11 +28,12 @@ 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_RESOLVE_SYMLINKS: When set to `1`/`true`, re-enable Webpack symlink resolution for `npm link`/pnpm workspace development. Default is `false` to improve performance and ensure consistent module identity (avoids duplicate module instances)
 - Source maps (dev): Dev builds emit external `.map` files next to JS bundles for CSP-safe debugging; production builds disable source maps
-- Symlinks: Webpack uses `resolve.symlinks: false` to improve performance and ensure consistent module identity; if you rely on `npm link`/pnpm workspaces, temporarily enable symlink resolution while developing linked packages
 
 Performance defaults: esbuild handles JS/CSS minification. In development, CSS is injected via style-loader; in production, CSS is extracted via MiniCssExtractPlugin. Thread-loader is enabled by default in both dev and prod.
 

build.mjs

@@ -32,7 +32,7 @@ const parallelBuild = getBooleanEnv(process.env.BUILD_PARALLEL, true)
 const isWatchOnce = getBooleanEnv(process.env.BUILD_WATCH_ONCE, false)
 // Cache compression control: default none; allow override via env
 function parseCacheCompressionOption(envVal) {
-  if (envVal == null) return undefined
+  if (envVal == null) return false
   const v = String(envVal).trim().toLowerCase()
   if (v === '' || v === '0' || v === 'false' || v === 'none') return false
   if (v === 'gzip' || v === 'brotli') return v
@@ -48,7 +48,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)) {
@@ -66,6 +66,7 @@ function parseThreadWorkerCount(envValue, cpuCount) {
 }
 const threadWorkers = parseThreadWorkerCount(process.env.BUILD_THREAD_WORKERS, cpuCount)
 // Thread-loader pool timeout constants (allow override via env)
+// Keep worker pool warm briefly to amortize repeated builds while still exiting quickly in CI
 let PRODUCTION_POOL_TIMEOUT_MS = 2000
 if (process.env.BUILD_POOL_TIMEOUT) {
   const n = parseInt(process.env.BUILD_POOL_TIMEOUT, 10)
@@ -79,6 +80,8 @@ if (process.env.BUILD_POOL_TIMEOUT) {
 }
 // Enable threads by default; allow disabling via BUILD_THREAD=0/false/no/off
 const enableThread = getBooleanEnv(process.env.BUILD_THREAD, true)
+// Allow opt-in symlink resolution for linked/workspace development when needed
+const resolveSymlinks = getBooleanEnv(process.env.BUILD_RESOLVE_SYMLINKS, false)
 
 // Cache and resolve Sass implementation once per process
 let sassImplPromise
@@ -93,8 +96,8 @@ async function getSassImplementation() {
           const mod = await import('sass')
           return mod.default || mod
         } catch (e2) {
-          console.error('[build] Failed to load sass-embedded:', e1 && e1.message ? e1.message : e1)
-          console.error('[build] Failed to load sass:', e2 && e2.message ? e2.message : e2)
+          console.error('[build] Failed to load sass-embedded:', e1)
+          console.error('[build] Failed to load sass:', e2)
           throw new Error("No Sass implementation available. Install 'sass-embedded' or 'sass'.")
         }
       }
@@ -166,7 +169,7 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
       // unnecessary cache invalidations across machines/CI runners
       version: JSON.stringify({ PROD: isProduction }),
       // default none; override via BUILD_CACHE_COMPRESSION=gzip|brotli
-      compression: cacheCompressionOption ?? false,
+      compression: cacheCompressionOption,
       buildDependencies: {
         config: [
           path.resolve('build.mjs'),
@@ -224,9 +227,8 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
     ],
     resolve: {
       extensions: ['.jsx', '.mjs', '.js'],
-      // Disable symlink resolution for consistent behavior/perf; note this can
-      // affect `npm link`/pnpm workspaces during local development
-      symlinks: false,
+      // Disable symlink resolution for consistent behavior/perf; enable via BUILD_RESOLVE_SYMLINKS=1 when working with linked deps
+      symlinks: resolveSymlinks,
       alias: {
         parse5: path.resolve(__dirname, 'node_modules/parse5'),
         ...(minimal
@@ -296,7 +298,12 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
             },
             {
               loader: 'sass-loader',
-              options: { implementation: sassImpl },
+              options: {
+                implementation: sassImpl,
+                sassOptions: {
+                  quietDeps: true,
+                },
+              },
             },
           ],
         },
@@ -399,10 +406,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) => {
@@ -424,18 +428,15 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
         } else {
           finishClose()
         }
-      } catch (err) {
-        console.error('[build] Callback error:', err)
+      } catch (callbackErr) {
+        console.error('[build] Callback error:', callbackErr)
         callbackFailed = true
         finishClose()
       }
     })
   } 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) {
@@ -504,7 +505,7 @@ async function copyFiles(entryPoints, targetDir) {
       try {
         await fs.copy(entryPoint.src, `${targetDir}/${entryPoint.dst}`)
       } catch (e) {
-        const isCss = String(entryPoint.dst).endsWith('.css')
+        const isCss = typeof entryPoint.dst === 'string' && entryPoint.dst.endsWith('.css')
         if (e && e.code === 'ENOENT') {
           if (!isProduction && isCss) {
             console.log(
@@ -613,7 +614,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
@@ -656,10 +657,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
@@ -674,6 +672,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