@dimina-kit/compiler 0.0.1 → 0.0.2-dev.20260711062001

package/README.md

@@ -160,17 +160,21 @@ Node 宿主（Electron devtools、CLI watch 服务等）用这个导出替代直
 
 dmcc 每次 `build()` 都新建 3 个 worker_threads、编完销毁，每次重编都要重新加载 sass/postcss/esbuild/oxc 并重启 esbuild 服务进程；本 pool 只在第一次付这笔钱。实测 watch 热重编（`dimina/fe/example` 全部 5 个 demo）比 dmcc 快 1.6–4×（base 826→207ms、weui 2716→763ms）；冷启动略慢于 dmcc（3 个 worker 首次加载 bundle），"打开一次、保存无数次"的 devtools 场景下净赚。数据与方法见 [`docs/compile-fs-experiments.md`](./docs/compile-fs-experiments.md)。
 
-**dmcc drop-in（默认导出）**——签名、返回值、日志面貌与 dmcc `build()` 一致，宿主原有的日志抓取（`✔ 输出编译产物` / `✖ <stage>` / `<workPath> 编译出错:`）不用改：
+**dmcc drop-in（默认导出）**——签名、成功返回值、日志面貌与 dmcc `build()` 一致，宿主原有的日志抓取（`✔ 输出编译产物` / `✖ <stage>` / `<workPath> 编译出错:`）不用改。**错误路径与 dmcc 刻意分歧：编译失败会 reject**（dmcc 吞错 resolve undefined，失败编译与"无 app 信息"从此不可区分，宿主会带着兜底 appId 启动一个只能 404 的会话）——失败时先照旧把 `✖ <stage>` + `编译出错:` 打到 stderr，再把错误抛给调用方：
 
 ```js
 import build from '@dimina-kit/compiler/pool-node'
 
 // 首次调用起常驻 worker,后续调用(watch 重编)复用
 const appInfo = await build(outputDir, workPath, true, { sourcemap: true, fileTypes })
-// 成功 → { appId, name, path };失败 → undefined(错误已打到 stderr,同 dmcc)
+// 成功 → { appId, name, path };编译失败 → reject(错误同时已打到 stderr,日志面貌同 dmcc)
 ```
 
-配套导出：`warmDefaultPool()` 提前创建这个 singleton 池并拉起 stage worker（不 build、无输出，项目无关——热备胎宿主在没有项目打开时调用,让第一次真实 build 从热池起步）；`disposeDefaultPool()` 显式回收。
+配套导出：`warmDefaultPool()` 提前创建这个 singleton 池并拉起 stage worker（不 build、无输出，项目无关——热备胎宿主在没有项目打开时调用,让第一次真实 build 从热池起步）；`disposeDefaultPool()` 显式回收；`oxcNativeBindingHint(message)` 把 oxc-parser 的 "Cannot find native binding" 报错映射成打包提示、`esbuildAsarSpawnHint(message)` 把 esbuild 二进制困在 app.asar 内的 spawn ENOENT 报错映射成 asarUnpack 提示（其他消息都返回 null）——stage 失败的 reject message 命中时会自动附带对应提示。
+
+> **Electron 打包分发注意（oxc-parser 运行时绑定）**：Node 编译路径依赖 oxc-parser，其运行时需要 `@oxc-parser/binding-<platform>-<arch>`（平台原生 `.node`）或 `@oxc-parser/binding-wasm32-wasi`（wasm 兜底）**二者之一实际存在于分发包内**。它们都不是宿主的直接依赖，electron-builder 等工具收集依赖时容易丢——丢了之后每次编译都在 logic stage 报 `Cannot find native binding`。宿主打包时请把其中一个显式声明为自己的 dependency（或在打包配置里强制收集）。
+
+> **Electron 打包分发注意（esbuild 原生二进制）**：esbuild 的 JS 库要 `child_process.spawn` 自己的平台二进制（`@esbuild/<platform>-<arch>` 里的 `esbuild.exe` / `bin/esbuild`），而 Electron 的 asar 补丁只覆盖 `execFile` 不覆盖 `spawn`——二进制留在 app.asar 内会必现 `spawn ... ENOENT`（Windows 报 `The service was stopped`，之后同一 realm 的每次调用都是 `The service is no longer running: write EPIPE`）。宿主打包配置需 `asarUnpack: ['**/node_modules/esbuild/**', '**/node_modules/@esbuild/**']`，并让 `ESBUILD_BINARY_PATH` 指向 app.asar.unpacked 下的真实文件（`@dimina-kit/devkit` 检测到自己跑在 asar 内时会自动设置）。
 
 **结构化用法（`createNodeCompilerPool`）**——要抛错误对象、显式回收 worker 时用：
 
@@ -193,6 +197,7 @@ try {
 - **写真实磁盘**（不经 `files` map），二进制静态资源完好——不受浏览器 `collectOutputs` utf8 限制。
 - **build 全局串行**：编译经过 dmcc 的进程级全局状态,所以同进程内所有 pool 实例的 build 共用一条串行链（并发调用会排队,不会互相污染产物）。
 - **worker 卡死/崩溃自愈**：与浏览器 pool 同一套监管（`src/worker-slot.js`）——卡死但没退出的 worker 在连续 `sendTimeoutMs`（默认 120s）无任何消息（worker 工作时每 2s 发心跳）后判死并**立即 terminate**；意外退出/超时导致的 build 失败默认**透明重试一次**（respawn 前先等旧 worker `terminate()` 结算,staging 目录由 setupCompile 重建,失败的那次不会污染重试产物）,重试仍失败才 reject（错误带 `.code` 与 `.stage`）。`retryOnWorkerDeath: false` 恢复"第一次死就报错"的单次语义。任何情况下后续 build 都不会永久挂起。
+- **工具链 service 死亡同样自愈**：esbuild 靠常驻的二进制子进程（service）干活,它死掉后（打包环境 spawn ENOENT、被 OOM/杀毒杀掉）该 worker realm 内的每次 esbuild 调用都永久报 `The service is no longer running: write EPIPE`——worker 线程还活着但已不可用。pool 把这类 stage 报错（`The service was stopped` / `is no longer running`）归类为 `.code === 'compiler-toolchain-dead'` 而非普通编译错误：命中的 worker 当场回收,享受与 worker 死亡相同的透明重试;环境修好后（如二进制就位）下一次 build 在新 realm 上自动恢复,不会带着死 service 永远失败。
 - **按 stage 懒加载工具链**：worker 在 spawn 时拿到自己的 stage 身份,只加载该 stage 的工具链——logic 只有 esbuild+oxc,view 只有 cheerio/@vue/compiler-sfc 系,style 才有 sass/cssnano/less;主线程一个重依赖都不加载。这依赖 node bundle 的 esbuild code-splitting(stage 编译器是运行时按需 import 的 chunk,见 `dist/pool.node-chunks/`),消费方无感。诊断:给 stage worker 发 `{ type: 'introspect' }` 会回 `{ type: 'introspect', stage, loaded: string[] }`(该 realm require cache 里实际出现的重依赖清单;纯 ESM 包如 cheerio 不经 CJS cache,天然不在此口径内)。
 - **idle 自动收缩**：最后一个 build 结束后闲置超过 `idleShrinkMs`（默认 5 分钟,`0`/`false`/`Infinity` 关闭）,pool 终止全部常驻 worker 释放内存（热 worker 组常驻数百 MB）;pool 本身仍可用,下一次 build 透明 respawn（重付 spawn+本 stage 工具链加载,秒级）。收缩绝不打断在途 build（计时只在队列排空后启动,新 build 到来即取消）,收缩后进程不会被遗留句柄钉住。
 - 运行时依赖（sass/postcss/esbuild/oxc 等）已声明为本包 dependencies,宿主无需再装 `@dimina/compiler`。