@dimina-kit/compiler 0.0.1-dev.20260706131625 → 0.0.1-dev.20260707070110

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimina-kit/compiler",
-  "version": "0.0.1-dev.20260706131625",
+  "version": "0.0.1-dev.20260707070110",
   "description": "dmcc compiler bundles (browser + node) that drive @dimina/compiler against a caller-injected node:fs replacement (no bundled fs)",
   "license": "MIT",
   "type": "module",
@@ -83,6 +83,7 @@
     "test:pool-node": "node scripts/build-compiler.js node && node --import ./scripts/register-kit.js scripts/test-pool-node.js",
     "test:pool-scopehash": "node scripts/build-compiler.js node && node --import ./scripts/register-kit.js scripts/test-pool-scopehash.js",
     "test:pool-hardening": "node scripts/build-compiler.js node && node scripts/test-pool-hardening.js",
+    "test:pool-toolchain-death": "node scripts/build-compiler.js node && node scripts/test-pool-toolchain-death.js",
     "test:pool-worker-hardening": "node scripts/test-pool-worker-hardening.js",
     "test:worker-slot": "node scripts/test-worker-slot.js",
     "test:pool-watchdog": "node scripts/test-pool-watchdog.js",

package/scripts/test-pool-toolchain-death.js

@@ -0,0 +1,135 @@
+// Regression coverage for the resident Node disk pool's handling of a DEAD esbuild
+// toolchain service — the Windows-packaged-app crash pattern: esbuild's JS lib spawns
+// a long-lived binary child process (the "service"), and in a packaged Electron app
+// that spawn can fail (e.g. the binary sits inside app.asar, which fs.existsSync()
+// sees but child_process.spawn() cannot exec). Once that service is dead inside a
+// warm worker realm, EVERY later esbuild call in that same realm fails with
+// "The service is no longer running: write EPIPE" — a message shape that looks
+// nothing like the real cause. Today the pool classifies this as
+// `code: 'compiler-stage-error'` ("deterministic, never retried") and keeps the
+// broken worker, so the pool never recovers even after the environment is healed.
+//
+// Fault injection needs no source changes: esbuild's node lib honors
+// ESBUILD_BINARY_PATH, and each worker_threads realm captures a COPY of
+// process.env at spawn. Pointing that var (before the pool spawns its workers) at
+// a real, executable file whose shebang interpreter does not exist reproduces the
+// exact "fs.existsSync() true, spawn() ENOENT" split a binary trapped inside
+// app.asar produces — child_process.spawn() reports ENOENT because the kernel's
+// own shebang-interpreter lookup fails, not because the file is missing.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const APP = process.env.APP_DIR
+  || fileURLToPath(new URL('../../../dimina/fe/example/base', import.meta.url))
+const TMP = fileURLToPath(new URL('../.tmp-pool-toolchain-death/', import.meta.url))
+fs.rmSync(TMP, { recursive: true, force: true })
+fs.mkdirSync(TMP, { recursive: true })
+const dir = (n) => path.join(TMP, n)
+
+const FAKE_ESBUILD = path.join(TMP, 'fake-esbuild-service')
+fs.writeFileSync(FAKE_ESBUILD, '#!/nonexistent/esbuild-interpreter\necho unreachable\n')
+fs.chmodSync(FAKE_ESBUILD, 0o755)
+
+let failed = false
+const chk = (cond, msg) => { if (!cond) { failed = true; console.error(`❌ ${msg}`) } else console.log(`✅ ${msg}`) }
+const withTimeout = (p, ms, label) => Promise.race([
+  p,
+  new Promise((_, rej) => setTimeout(() => rej(new Error(`TIMEOUT: ${label} did not settle in ${ms}ms`)), ms).unref()),
+])
+const settle = (p) => p.then((v) => ({ ok: true, v }), (e) => ({ ok: false, e }))
+const treeOk = (d, i) => fs.existsSync(path.join(d, i.appId, 'main', 'logic.js'))
+
+// Property access (not a named import) so a dist build that has not yet added
+// esbuildAsarSpawnHint fails this script's own assertion instead of a module-link
+// SyntaxError that would abort before any other scenario runs.
+const poolModule = await import('../dist/pool.node.js')
+const { createNodeCompilerPool } = poolModule
+const esbuildAsarSpawnHint = poolModule.esbuildAsarSpawnHint
+
+// --- classification + recycle ------------------------------------------------------
+// A dead esbuild service must be coded distinctly from a real compile error, and the
+// worker(s) that hit it must be recycled so the NEXT build — once the environment is
+// healed — runs on a fresh realm instead of replaying the same dead service forever.
+process.env.ESBUILD_BINARY_PATH = FAKE_ESBUILD
+const pool = createNodeCompilerPool({ retryOnWorkerDeath: false })
+// Read immediately after creation, before the pool's own eager ensureAlive() settles —
+// the pristine pre-spawn baseline every later generation count is compared against.
+const gensPristine = pool._slots.map((x) => x.slot.generation)
+
+const first = await withTimeout(
+  settle(pool.build(dir('a1'), APP, true, {})), 60000, 'first build against a dead esbuild service',
+)
+chk(!first.ok, 'first build against a dead esbuild service rejects')
+const firstErr = first.ok ? null : first.e
+chk(!!firstErr && firstErr.code === 'compiler-toolchain-dead',
+  `dead-esbuild-service failure is coded 'compiler-toolchain-dead' (got ${firstErr && firstErr.code})`)
+chk(!!firstErr && typeof firstErr.stage === 'string' && firstErr.stage.length > 0,
+  `error carries .stage (got ${firstErr && firstErr.stage})`)
+chk(!!firstErr && /^\[compiler\] stage "[^"]+" failed: .*The service (was stopped|is no longer running)/.test(firstErr.message || ''),
+  `error message keeps the stage-shaped prefix around the dead-service cause: ${firstErr && firstErr.message}`)
+
+// Heal the environment the way a real fix would (repackage / relaunch): only NEWLY
+// spawned worker realms see this — the pool must actually recycle, not get lucky that
+// the already-spawned realm somehow un-breaks itself.
+delete process.env.ESBUILD_BINARY_PATH
+
+const second = await withTimeout(
+  settle(pool.build(dir('a2'), APP, true, {})), 60000, 'build after healing the toolchain env',
+)
+chk(second.ok && treeOk(dir('a2'), second.v),
+  `build after healing the env succeeds via recycled workers, not a permanent write EPIPE: ${second.ok ? 'ok' : second.e && second.e.message}`)
+
+const gensAfterHeal = pool._slots.map((x) => x.slot.generation)
+chk(gensAfterHeal.some((g, i) => g - gensPristine[i] > 1),
+  `pool recycled at least one worker slot between the dead-service failure and the next build (pristine ${gensPristine.join(',')} -> after-heal ${gensAfterHeal.join(',')})`)
+
+await pool.dispose()
+
+// --- transparent retry on a persistently broken toolchain --------------------------
+// retryOnWorkerDeath defaults to true and already gives worker crashes one whole-build
+// retry; a dead-toolchain failure must get the same treatment. With the environment
+// STILL broken the retry cannot succeed either, so the build must still reject (no
+// hang) — but by then the affected slot(s) should have been recycled on both the
+// initial attempt and its retry.
+process.env.ESBUILD_BINARY_PATH = FAKE_ESBUILD
+const poolR = createNodeCompilerPool() // retryOnWorkerDeath defaults to true
+const gensPristineR = poolR._slots.map((x) => x.slot.generation)
+
+const retried = await withTimeout(
+  settle(poolR.build(dir('r1'), APP, true, {})), 120000, 'build against a persistently dead esbuild service with retry enabled',
+)
+chk(!retried.ok, 'build against a persistently dead toolchain still rejects rather than hanging')
+chk(!retried.ok && retried.e && retried.e.code === 'compiler-toolchain-dead',
+  `the final rejection after the transparent retry is still coded 'compiler-toolchain-dead' (got ${retried.ok ? undefined : retried.e && retried.e.code})`)
+
+const gensAfterRetry = poolR._slots.map((x) => x.slot.generation)
+chk(gensAfterRetry.some((g, i) => g - gensPristineR[i] > 1),
+  `a persistently dead toolchain is recycled on both the initial attempt and its retry (pristine ${gensPristineR.join(',')} -> after-retry ${gensAfterRetry.join(',')})`)
+
+await poolR.dispose()
+delete process.env.ESBUILD_BINARY_PATH
+
+// --- pure helper: actionable asar-unpack hint for a dead esbuild service ------------
+chk(typeof esbuildAsarSpawnHint === 'function', 'esbuildAsarSpawnHint is exported from the pool module')
+if (typeof esbuildAsarSpawnHint === 'function') {
+  const asarMsg = 'The service was stopped: spawn C:\\Users\\x\\AppData\\Local\\Programs\\myapp\\resources\\app.asar\\node_modules\\@esbuild\\win32-x64\\esbuild.exe ENOENT'
+  const hint = esbuildAsarSpawnHint(asarMsg)
+  chk(typeof hint === 'string' && /asarUnpack/.test(hint),
+    `an asar-packaged esbuild ENOENT message gets an asarUnpack hint (got ${JSON.stringify(hint)})`)
+
+  const syntaxMsg = 'Transform failed with 1 error:\nfile.js:1:1: ERROR: Unexpected "}"'
+  chk(esbuildAsarSpawnHint(syntaxMsg) === null,
+    `an unrelated esbuild syntax error gets no hint (got ${JSON.stringify(esbuildAsarSpawnHint(syntaxMsg))})`)
+
+  const oxcMsg = 'Cannot find native binding. Napi module could not be resolved.'
+  chk(esbuildAsarSpawnHint(oxcMsg) === null,
+    `an oxc native-binding message (oxcNativeBindingHint's own territory) gets no hint here (got ${JSON.stringify(esbuildAsarSpawnHint(oxcMsg))})`)
+} else {
+  failed = true
+  console.error('❌ skipped esbuildAsarSpawnHint behavior checks (not exported)')
+}
+
+fs.rmSync(TMP, { recursive: true, force: true })
+console.log(failed ? '\n❌ FAIL' : '\n✅ PASS: dead-esbuild-service classification, recycle-on-failure, retry-still-rejects, asar hint')
+process.exit(failed ? 1 : 0)

package/src/pool-node.js

@@ -38,7 +38,18 @@ const { Worker } = createRequire(import.meta.url)('node:worker_threads')
 // generous than the browser default: disk builds run whole real projects.
 const DEFAULT_SEND_TIMEOUT_MS = 120000
 
-const WORKER_DEATH_CODES = new Set(['compiler-worker-timeout', 'compiler-worker-crashed', 'compiler-worker-dead'])
+// 'compiler-toolchain-dead' belongs here even though the worker THREAD is alive: the
+// realm's esbuild service child process is gone, so the realm is just as unusable as a
+// crashed worker — the same one-retry-on-fresh-workers policy applies.
+const WORKER_DEATH_CODES = new Set(['compiler-worker-timeout', 'compiler-worker-crashed', 'compiler-worker-dead', 'compiler-toolchain-dead'])
+
+// esbuild's node lib drives a spawned long-lived binary child (its "service"). When that
+// child dies (spawn ENOENT in a packaged app, OOM kill, AV kill), esbuild reports every
+// call with one of these two phrases — and the service NEVER restarts inside that realm,
+// so the warm worker is permanently broken and must be recycled, not kept.
+function isDeadToolchainServiceError(message) {
+  return /The service (was stopped|is no longer running)/.test(String(message))
+}
 
 // Default idle window before the pool shrinks (terminates its resident stage workers to
 // release their memory — a warm worker set holds hundreds of MB of toolchain + compile
@@ -164,18 +175,33 @@ export function createNodeCompilerPool({
         if (err && err.code && !err.stage) err.stage = x.stage
         throw err
       })))
-    for (const r of results) {
-      if (!r || r.type === 'error') {
-        const info = r && r.error
-        const cause = (info && info.message) || 'unknown error'
-        const hint = oxcNativeBindingHint(cause)
-        const err = new Error(`[compiler] stage "${r && r.stage}" failed: ${cause}${hint ? ` — ${hint}` : ''}`)
-        if (info && info.stack) err.stack = info.stack
-        err.stage = r && r.stage
+    // Walk EVERY result before throwing: when more than one stage hit a dead toolchain
+    // service (logic and view both drive esbuild), each broken realm must be recycled
+    // now — throwing on the first would leave the sibling's dead service warm, and the
+    // next build would fail on it all over again.
+    let firstErr = null
+    for (let i = 0; i < results.length; i++) {
+      const r = results[i]
+      if (r && r.type !== 'error') continue
+      const info = r && r.error
+      const cause = (info && info.message) || 'unknown error'
+      const hint = oxcNativeBindingHint(cause) || esbuildAsarSpawnHint(cause)
+      const err = new Error(`[compiler] stage "${r && r.stage}" failed: ${cause}${hint ? ` — ${hint}` : ''}`)
+      if (info && info.stack) err.stack = info.stack
+      err.stage = r && r.stage
+      if (isDeadToolchainServiceError(cause)) {
+        // The realm's toolchain service child is dead and never comes back — terminate
+        // the worker so the next attempt (the transparent retry, or the next build once
+        // the environment is healed) respawns a fresh realm with a fresh service.
+        // shrink() is safe here: settleAll above guarantees no request is in flight.
+        err.code = 'compiler-toolchain-dead'
+        workers[i].slot.shrink()
+      } else {
         err.code = 'compiler-stage-error' // worker-reported compile error — never retried
-        throw err
       }
+      if (!firstErr) firstErr = err
     }
+    if (firstErr) throw firstErr
 
     // 3) Publish the staging dir to the caller's outputDir (dmcc-identical layout).
     publishToDist(outputDir, useAppIdDir)
@@ -234,6 +260,24 @@ export function createNodeCompilerPool({
 // user-facing compile-log lines a host (e.g. devkit/devtools' log panel) already scrapes.
 const STAGE_TITLES = { logic: '编译页面逻辑', view: '编译页面文件', style: '编译样式文件' }
 
+/**
+ * Map a failure message to an actionable packaging hint when it is esbuild failing to
+ * spawn its native binary from inside an Electron app.asar archive. Electron patches
+ * child_process.execFile for asar paths but NOT child_process.spawn (which esbuild
+ * uses), so an in-archive binary path always ENOENTs at spawn even though fs sees the
+ * file — the raw message points at a path that plainly exists, which is why it needs
+ * a hint. Returns null for every other message.
+ * @param {string} message
+ * @returns {string | null}
+ */
+export function esbuildAsarSpawnHint(message) {
+  const msg = String(message)
+  if (!/app\.asar/.test(msg) || !/esbuild/i.test(msg) || !/ENOENT/.test(msg)) return null
+  return 'esbuild 的原生二进制无法从 app.asar 内 spawn（Electron 只为 execFile 打 asar 补丁）：'
+    + "打包配置需 asarUnpack '**/node_modules/esbuild/**' 与 '**/node_modules/@esbuild/**'，"
+    + '并确保 ESBUILD_BINARY_PATH 指向 app.asar.unpacked 下的真实二进制（@dimina-kit/devkit 在 asar 内运行时会自动设置）'
+}
+
 /**
  * Map a failure message to an actionable packaging hint when it is oxc-parser's
  * "missing runtime binding" error (thrown when NEITHER the platform-native