wsemi 1.9.13 → 1.9.15

package/src/alive.mjs

@@ -2,7 +2,7 @@ import get from 'lodash-es/get.js'
 import each from 'lodash-es/each.js'
 import cloneDeep from 'lodash-es/cloneDeep.js'
 import size from 'lodash-es/size.js'
-import cst from './_const.mjs'
+import cst from './_const.mjs'
 import evem from './evem.mjs'
 import evEmit from './evEmit.mjs'
 import ispint from './ispint.mjs'
@@ -19,7 +19,7 @@ import cint from './cint.mjs'
  * @memberOf wsemi
  * @param {Integer} [timeAlive=10000] 輸入判斷單元是否斷線之延時整數，單位為毫秒ms，預設為10000
  * @param {Integer} [timeDetect=50] 輸入偵測佇列間隔時間整數，單位為毫秒ms，預設為50
- * @returns {Object} 回傳事件物件，可呼叫函數on、trigger、get。trigger給予單元的唯一key字串與攜帶數據data物件，on為監聽事件，需自行監聽message事件取得單元進出事件。get事件可取得alive內視為存活的單元清單。事件物件為原生EventEmitter(eventemitter3)。本模組於派發處以try攔截監聽器之同步拋錯，故其不會使行程崩潰，會改以error事件回報{ fun: 'listener', name, msg, args }，無error監聽者則console.error；惟依EventEmitter規範，同一次派發中先拋錯之監聽器會中止該次派發，其後之監聽器不再被呼叫。async監聽器之reject不被攔截(規範上emit不觀察監聽器回傳值)，須由監聽器自行處理，否則為unhandledRejection
+ * @returns {Object} 回傳事件物件，可呼叫函數on、trigger、get、clear。trigger給予單元的唯一key字串與攜帶數據data物件，on為監聽事件，需自行監聽message事件取得單元進出事件。get事件可取得alive內視為存活的單元清單(含剛trigger而尚未發出enter者)。clear為釋放：立即清除偵測計時器、取消尚未發出之enter、清空佇列，本身不發事件，其後不再發出任何事件、trigger無效、get回傳[]，可重複呼叫(釋放為終態，需重新偵測者另建alive)；clear回傳已發出enter且尚未leave之單元陣列[{ key, data }]，供使用端補發離線通知，再次呼叫回傳[]；監聽器於派發中呼叫clear亦安全，同一輪尚未處理之單元不再派發。事件物件為原生EventEmitter(eventemitter3)。本模組於派發處以try攔截監聽器之同步拋錯，故其不會使行程崩潰，會改以error事件回報{ fun: 'listener', name, msg, args }，無error監聽者則console.error；惟依EventEmitter規範，同一次派發中先拋錯之監聽器會中止該次派發，其後之監聽器不再被呼叫。async監聽器之reject不被攔截(規範上emit不觀察監聽器回傳值)，須由監聽器自行處理，否則為unhandledRejection
  * @example
  *
  * async function topAsync() {
@@ -81,14 +81,47 @@ import cint from './cint.mjs'
  *     // 4544ms { eventName: 'leave', key: 'b', data: { data: '34.56' }, now: 0 }
  *     // ["enter|a","enter|b","leave|b","enter|b","leave|a","leave|b"]
  *
+ *     function test2() {
+ *         return new Promise((resolve, reject) => {
+ *             let ms = []
+ *
+ *             let oAL = alive({ timeAlive: 1500 })
+ *
+ *             oAL.on('message', function({ eventName, key }) {
+ *                 ms.push(eventName + '|' + key)
+ *             })
+ *
+ *             oAL.trigger('a', { data: 123 })
+ *
+ *             setTimeout(() => {
+ *                 oAL.trigger('b', { data: '34.56' })
+ *                 let r = oAL.clear() //b剛trigger尚未發出enter, 故只回傳a, 且b之enter不再發出
+ *                 ms.push('clear|' + r.map((v) => v.key).join(','))
+ *             }, 500)
+ *
+ *             setTimeout(() => {
+ *                 resolve(ms)
+ *             }, 2500)
+ *
+ *         })
+ *     }
+ *     console.log('test2')
+ *     let r2 = await test2()
+ *     console.log(JSON.stringify(r2))
+ *     // test2
+ *     // ["enter|a","clear|a"]
+ *
  * }
  * topAsync().catch(() => {})
  *
  */
 function alive(opt = {}) {
     let ev = evem() //message事件於timer內派發, 監聽器出錯不得殺行程, 故派發處以evEmit攔截
-    let q = {} //queue
+    let q = Object.create(null) //queue, 以trigger之key為鍵; 用無原型物件使任意字串皆為一般鍵, 一般物件時__proto__會改掉佇列之原型、constructor等原型屬性名會被haskey誤判為已存在而不發enter
     let t = null //timer
+    let tEnters = new Set() //尚未發出enter之計時器, 供clear取消
+    let entered = new Set() //已發出enter且尚未leave之單元key, 供clear回傳
+    let cleared = false //是否已clear, clear為終態
 
     //timeAlive
     let timeAlive = get(opt, 'timeAlive')
@@ -107,6 +140,9 @@ function alive(opt = {}) {
     timeDetect = Math.min(timeDetect, cst.TIMER_TIME_MAX) //同上
 
     function detect() {
+        if (cleared) {
+            return
+        }
         if (t !== null) {
             return
         }
@@ -127,13 +163,25 @@ function alive(opt = {}) {
 
                     //刪除佇列內key紀錄
                     delete q[key]
+                    entered.delete(key)
 
                     //emit leave
                     evEmit(ev, 'message', [{ eventName: 'leave', key, data: r.data, now: size(q) }], { tag: 'alive' })
 
+                    //監聽器於派發中呼叫clear時須立即停止本輪, 不再處理或派發
+                    //  each走的是本輪開始時之鍵清單, 而clear已清空佇列, 續走會讀到不存在之單元而拋錯
+                    if (cleared) {
+                        return false
+                    }
+
                 }
             })
 
+            //已clear者計時器已於clear內清除
+            if (cleared) {
+                return
+            }
+
             //clear, 當無任何訊息存在
             if (!iseobj(q)) {
                 clearInterval(t)
@@ -145,6 +193,11 @@ function alive(opt = {}) {
 
     function trigger(key, data) {
 
+        //已clear為終態, 不建立計時器亦不發事件
+        if (cleared) {
+            return
+        }
+
         //check
         if (!isestr(key)) {
             console.log('trigger need key')
@@ -153,12 +206,23 @@ function alive(opt = {}) {
 
         //check
         if (!haskey(q, key)) {
-            setTimeout(() => { //因需判斷是否為新單元故需放於update前, 而emit內可能會被存取q, 故需要用setTimeout脫勾使q為被更新資訊, 才能正確取得當前單元數量
+            //因需判斷是否為新單元故需放於update前, 而emit內可能會被存取q, 故需要用setTimeout脫勾使q為被更新資訊, 才能正確取得當前單元數量
+            //不用evEmitDelay, 因其參數於呼叫時即求值, now會少計本單元; 計時器存入tEnters供clear取消
+            let te = setTimeout(() => {
+
+                //已發出, 移出待取消清單
+                tEnters.delete(te)
+
+                //派發前即標記已enter, 使監聽器於派發中呼叫clear時能回傳本單元, 以與其leave配對
+                if (haskey(q, key)) {
+                    entered.add(key)
+                }
 
                 //emit enter
                 evEmit(ev, 'message', [{ eventName: 'enter', key, data, now: size(q) }], { tag: 'alive' })
 
             }, 1)
+            tEnters.add(te)
         }
 
         //update
@@ -178,9 +242,46 @@ function alive(opt = {}) {
         return rs
     }
 
+    function clear() {
+
+        //已clear則回傳[], 可重複呼叫
+        if (cleared) {
+            return []
+        }
+        cleared = true
+
+        //清除偵測計時器
+        if (t !== null) {
+            clearInterval(t)
+            t = null
+        }
+
+        //取消尚未發出之enter
+        for (let te of tEnters) {
+            clearTimeout(te)
+        }
+        tEnters.clear()
+
+        //已發出enter且尚未leave之單元, 形狀同get; get含尚未發出enter者, 使用端拿其配對leave會出現有leave無enter
+        let rs = []
+        each(q, (v, k) => {
+            if (entered.has(k)) {
+                rs.push({ key: k, data: v.data })
+            }
+        })
+        rs = cloneDeep(rs) //使用cloneDeep避免外部修改內部數據
+
+        //清空佇列, 同建立時用無原型物件
+        q = Object.create(null)
+        entered.clear()
+
+        return rs
+    }
+
     //save
     ev.trigger = trigger
     ev.get = _get
+    ev.clear = clear
 
     return ev
 }

package/src/cache.mjs

@@ -1,7 +1,7 @@
 import loGet from 'lodash-es/get.js'
 import cloneDeep from 'lodash-es/cloneDeep.js'
 import evem from './evem.mjs'
-import evEmitDelay from './evEmitDelay.mjs'
+import evEmitDelay from './evEmitDelay.mjs'
 import isfun from './isfun.mjs'
 import isbol from './isbol.mjs'
 import haskey from './haskey.mjs'
@@ -538,7 +538,7 @@ import cint from './cint.mjs'
  */
 function cache() {
     let ev = evem() //事件以timer脫勾派發, 監聽器出錯不得殺行程, 故派發處以evEmit攔截
-    let data = {} //快取資料
+    let data = Object.create(null) //快取資料, 以呼叫端之key為鍵; 用無原型物件使任意字串皆為一般鍵, 一般物件時__proto__會改掉其原型、constructor等原型屬性名會被haskey誤判為已存在, 對其update會寫到Object本身
 
     function emit(mode, data) {
         evEmitDelay(ev, mode, [data], { tag: 'cache' }) //用timer脫勾, 並於該新堆疊內攔截監聽器之同步拋錯

package/src/cacheSt.mjs

@@ -112,7 +112,7 @@ function cacheSt(opt = {}) {
 
     let ev = evem() //detect事件於setInterval內派發, 其餘於呼叫端同步堆疊或await之後派發且監聽器可能為async, 監聽器出錯不得殺行程, 故派發處以evEmit攔截
 
-    let _gs = {}
+    let _gs = Object.create(null) //以呼叫端之key為鍵; 用無原型物件使任意字串皆為一般鍵, 一般物件時__proto__會改掉其原型(且不會過期)、constructor等原型屬性名會被haskey誤判為已存在
 
     let _set = async (key, value = true) => {
         _gs[key] = {

package/src/evEmit.mjs

@@ -16,7 +16,7 @@ import isfun from './isfun.mjs'
  *
  * setTimeout會開一個「沒有呼叫者」的堆疊，監聽器之同步拋錯於該處即為uncaughtException，
  * 且呼叫端無論如何try都攔不到（此與監聽器是否為async無關，純同步監聽器亦然）。
- * 於呼叫端之堆疊上派發，一個普通的try即可攔下。確實需要脫勾者請改用evEmitDefer，
+ * 於呼叫端之堆疊上派發，一個普通的try即可攔下。確實需要脫勾者請改用evEmitDelay，
  * 其內部即以本函數派發，故仍有攔截。
  *
  * 【為何不處理async監聽器之reject】

package/src/execCli.mjs

@@ -16,12 +16,17 @@ import strdelleft from './strdelleft.mjs'
 import strTruncate from './strTruncate.mjs'
 import execProcessKillPid from './execProcessKillPid.mjs'
 import execCliCore from './execCliCore.mjs'
+import execSpawnError from './_execSpawnError.mjs'
 
 
 //buildSpawnArgs, buildSpawnEnv, 共用核心已抽至execCliCore
 let { buildSpawnArgs, buildSpawnEnv } = execCliCore
 
 
+//kNoRetry, 無法啟動子進程之同步錯誤所產生之結果物件(確定性失敗, 重試無意義), 供execCli判定不重試, 不擴充對外之結果物件欄位
+let kNoRetry = new WeakSet()
+
+
 //optTruncate, 供strTruncate裁切失敗結果之stdout與stderr時, 於刪節號後標註原始總長度
 let optTruncate = {
     funWithMsg: (str) => `(truncated, total ${str.length} chars)`,
@@ -126,15 +131,33 @@ function execCliOnce(command, args = [], opt = {}) {
     //每次attempt於此重新求值並僅作用於該次子進程, 不動本進程process.env, 故並行調用可各自帶不同值
     let envSpawn = buildSpawnEnv(envExtra)
 
-    //spawn
-    let winSpawn = buildSpawnArgs(command, args)
-    let proc = spawn(winSpawn.file, winSpawn.args, {
-        cwd,
-        stdio: ['pipe', 'pipe', 'pipe'],
-        windowsHide: true, //執行的主程序若沒有主控台調用執行程序就不會有視窗, 但若通過pm2執行會有, 須設定windowsHide=true
-        env: envSpawn,
-        ...winSpawn.opt,
-    })
+    //spawn, 同步拋錯(EPERM、UNKNOWN、ENAMETOOLONG、參數檢查錯誤等)以結果物件回報而不reject, 且屬確定性失敗不重試; buildSpawnArgs之拋錯亦同
+    let proc
+    try {
+        let winSpawn = buildSpawnArgs(command, args)
+        proc = spawn(winSpawn.file, winSpawn.args, {
+            cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true, //執行的主程序若沒有主控台調用執行程序就不會有視窗, 但若通過pm2執行會有, 須設定windowsHide=true
+            env: envSpawn,
+            ...winSpawn.opt,
+        })
+    }
+    catch (err) {
+        let e = execSpawnError(err)
+        let r = {
+            ok: false,
+            stdout: '',
+            stderr: '',
+            code: null,
+            error: `${e.code}: ${e.message}`,
+            durationMs: Date.now() - startTime,
+            pid: undefined, //與'error'事件(如ENOENT)之結果一致
+        }
+        kNoRetry.add(r)
+        pm.resolve(r)
+        return pm
+    }
 
     let stdout = ''
     let stderr = ''
@@ -146,6 +169,32 @@ function execCliOnce(command, args = [], opt = {}) {
 
     let settled = false
     let timedOut = false
+    let timer = null
+
+    //error, 須於存取stdio前監聽: node對EMFILE、ENFILE不建立stdio即於nextTick發出'error', 先存取會拋TypeError且'error'無人監聽而拉倒程序
+    //  可能為'找不到可執行檔'(ENOENT), '權限不足', '系統資源用盡'等, 訊息經execSpawnError去除參數值
+    proc.on('error', (err) => {
+        if (settled) {
+            return
+        }
+        settled = true
+        clearTimeout(timer)
+        let e = execSpawnError(err)
+        pm.resolve({
+            ok: false,
+            stdout: '',
+            stderr: '',
+            code: null,
+            error: `${e.code}: ${e.message}`,
+            durationMs: Date.now() - startTime,
+            pid: proc.pid,
+        })
+    })
+
+    //stdio, EMFILE、ENFILE時node未建立(undefined), 由上方error回報
+    if (!proc.stdout || !proc.stderr || !proc.stdin) {
+        return pm
+    }
 
     //stdout data, 經TextDecoder跨chunk解碼
     proc.stdout.on('data', (chunk) => {
@@ -183,7 +232,7 @@ function execCliOnce(command, args = [], opt = {}) {
     proc.stdin.end()
 
     //timer, 逾時觸發時調用execProcessKillPid殺整棵程序樹
-    let timer = setTimeout(() => {
+    timer = setTimeout(() => {
         if (settled) {
             return
         }
@@ -213,24 +262,6 @@ function execCliOnce(command, args = [], opt = {}) {
 
     }, timeoutMs)
 
-    //error, 監聽(例如執行spawn本身)錯誤訊息, 可能為'找不到可執行檔'(ENOENT), '權限不足', '系統資源用盡'等
-    proc.on('error', (err) => {
-        if (settled) {
-            return
-        }
-        settled = true
-        clearTimeout(timer)
-        pm.resolve({
-            ok: false,
-            stdout: '',
-            stderr: '',
-            code: null,
-            error: `${err.code || 'UNKNOWN'}: ${err.message}`,
-            durationMs: Date.now() - startTime,
-            pid: proc.pid,
-        })
-    })
-
     //close
     proc.on('close', (code, signal) => {
         if (settled) {
@@ -314,7 +345,7 @@ function execCliOnce(command, args = [], opt = {}) {
  * 通用CLI子程序調用，封裝逾時、進程樹清理、輸出驗證、結構化錯誤回報與自動重試
  * 各參數原樣傳遞給目標CLI，支援中文
  * Windows下npm全域安裝之命令為.cmd批次檔，Node.js spawn無法直接執行(CVE-2024-27980安全修正後回EINVAL)，內部已參考cross-spawn自動解析.cmd入口並繞過cmd.exe，故可支援含多行文字之參數
- * 本函數不throw，一律以結果物件之ok與error欄位回報成敗
+ * 本函數不throw，一律以結果物件之ok與error欄位回報成敗，error不含args與env之值(子程序自身之輸出另見stdout、stderr)
  *
  * Unit Test: {@link https://github.com/yuda-lyu/wsemi/blob/master/test/execCli.test.mjs Github}
  * @memberOf wsemi
@@ -326,10 +357,10 @@ function execCliOnce(command, args = [], opt = {}) {
  * @param {String} [opt.input=undefined] 輸入傳入子進程stdin之字串，預設undefined代表不寫入stdin
  * @param {String|Function} [opt.validate=undefined] 輸入stdout驗證規則字串或自訂驗證函數，規則字串支援'nonempty'(非空)、'json'(可JSON.parse)、'min:100'(長度下限)，多規則可用逗號串接例如'nonempty,json'，自訂函數為(stdout)=>Boolean，預設undefined代表不驗證
  * @param {Number} [opt.maxBuffer=10485760] 輸入stdout與stderr各自累積之最大字元數正整數，超過部分將不再累積，預設10485760(10MB)
- * @param {Function} [opt.onStdout=undefined] 輸入stdout串流回調函數，格式為(chunk)=>{}，預設undefined
- * @param {Function} [opt.onStderr=undefined] 輸入stderr串流回調函數，格式為(chunk)=>{}，預設undefined
+ * @param {Function} [opt.onStdout=undefined] 輸入stdout串流回調函數，格式為(chunk)=>{}，回調內拋出之錯誤不會被攔截，將成為未捕捉例外，請於回調內自行處理，預設undefined
+ * @param {Function} [opt.onStderr=undefined] 輸入stderr串流回調函數，格式為(chunk)=>{}，行為同onStdout，預設undefined
  * @param {Object} [opt.env=undefined] 輸入本次調用額外注入之環境變數物件，會併入process.env之後(同名以此為準，含PYTHONIOENCODING)，僅作用於該次子進程而不影響本進程之process.env，故並行調用可各自帶不同值；值為undefined代表移除該變數(可遮蔽繼承值)，值為null會成為字面字串'null'故建議勿傳；Windows下環境變數大小寫不敏感，同名不同大小寫(如Path與PATH)亦視為同名覆蓋，預設undefined代表不覆寫任何變數
- * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，遇ENOENT(命令不存在)或exit code 2(參數錯誤)視為不可重試而立即中止，預設0
+ * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，遇ENOENT(命令不存在)、exit code 2(參數錯誤)或無法啟動子進程之同步錯誤(如參數過長、權限不足、非有效執行檔、參數含空字元)視為不可重試而立即中止，預設0
  * @param {Number} [opt.retryDelayMs=5000] 輸入重試間隔毫秒正整數，實際間隔為retryDelayMs乘以重試次數且上限15000ms，預設5000
  * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(標準輸出字串)、stderr(標準錯誤字串)、code(離開碼)、error(錯誤訊息字串，成功時為空字串)、durationMs(耗時毫秒)、pid(子進程pid)、attempts(實際嘗試次數)
  * @example
@@ -508,6 +539,9 @@ async function execCli(command, args = [], opt = {}) {
         }
 
         //不可重試的錯誤
+        if (kNoRetry.has(lastResult)) {
+            break //無法啟動子進程之同步錯誤(參數過長、權限不足、非有效執行檔、參數檢查錯誤等), 重試無意義
+        }
         if (lastResult.error.includes('ENOENT')) {
             break //命令不存在, 重試無意義
         }

package/src/execCliCore.mjs

@@ -78,6 +78,9 @@ function resolveCommand(cmd) {
  */
 function escapeWinArg(arg) {
 
+    //String, 非字串元素比照node之spawn轉為字串(否則.replace拋TypeError)
+    arg = String(arg)
+
     //轉義反斜線 + 雙引號 組合
     arg = arg.replace(/(\\*)"/g, '$1$1\\"')
 

package/src/execCliJsonRpc.mjs

@@ -12,7 +12,7 @@ import execCliSession from './execCliSession.mjs'
 /**
  * 對stdio協定型CLI依序送出一行一則JSON之請求並收集回應(疊於execCliSession之上)，適用codex app-server、MCP之stdio伺服器等以換行分隔JSON之協定(LSP為Content-Length分幀，不適用)
  * 不內建任何協定知識，initialize/initialized等握手由呼叫端以請求陣列表達
- * 本函數不throw，一律以結果物件之ok與error、errorType欄位回報成敗
+ * 本函數不throw，一律以結果物件之ok與error、errorType欄位回報成敗，error不含args與env之值
  *
  * 規則:
  *   - 請求物件含method者為請求，自動配id(自0遞增)並等待同id之回應；含notify者為通知，不配id，送出即繼續
@@ -34,7 +34,7 @@ import execCliSession from './execCliSession.mjs'
  * @param {Boolean} [opt.continueOnError=false] 輸入回應含error時是否繼續送出後續請求布林值，預設false
  * @param {Function} [opt.onNotify=undefined] 輸入伺服器通知(無id訊息)回調函數，格式為(msg)=>{}，預設undefined
  * @param {Function} [opt.onServerRequest=undefined] 輸入伺服器發給客戶端之請求(帶id且含method)回調函數，格式為(msg, session)=>{}，可用session.writeLine回覆，預設undefined
- * @param {Function} [opt.onStderr=undefined] 輸入stderr片段回調函數，格式為(chunk)=>{}，預設undefined
+ * @param {Function} [opt.onStderr=undefined] 輸入stderr片段回調函數，格式為(chunk)=>{}，預設undefined。onNotify、onServerRequest、onStderr內拋出之錯誤不會被攔截，將成為未捕捉例外，請於回調內自行處理
  * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否全部成功布林值)、results(以method為鍵之result物件，失敗者為null)、responses(依序之回應陣列，每項為{ id, method, result, error })、error(錯誤訊息字串，成功時為空字串)、errorType(錯誤類型字串: params(參數錯誤)、notfound(命令不存在)、timeout(逾時)、exit(子進程於回應前結束)、rpc(回應含error)，成功時為空字串)、durationMs(耗時毫秒)、exitCode(子進程離開碼)
  * @example
  * //need test in nodejs

package/src/execCliSession.mjs

@@ -10,6 +10,7 @@ import ispint from './ispint.mjs'
 import isp0int from './isp0int.mjs'
 import execProcessKillPid from './execProcessKillPid.mjs'
 import execCliCore from './execCliCore.mjs'
+import execSpawnError from './_execSpawnError.mjs'
 
 
 //buildSpawnArgs, buildSpawnEnv, 共用核心
@@ -19,7 +20,7 @@ let { buildSpawnArgs, buildSpawnEnv } = execCliCore
 /**
  * 建立互動式stdio工作階段(session)，用於stdio協定型之長駐CLI(如MCP之stdio伺服器、codex app-server等一行一則JSON之程式)，與execCli「寫完input即關閉stdin並等待結束」之一次性契約不同，本函數維持stdin開啟，由呼叫端逐次write，直到呼叫stop()才關閉stdin並等待子進程自行退出，逾寬限期則以execProcessKillPid樹殺
  * Windows下npm全域安裝之命令為.cmd批次檔，內部經execCliCore.buildSpawnArgs解析為以node執行其JS入口，不使用shell:true，故樹殺可確實涵蓋子孫程序
- * 本函數不throw亦不reject，spawn失敗(如ENOENT)以onExit與stop()之結果物件回報
+ * 本函數不throw亦不reject，spawn失敗(如ENOENT)以onExit與stop()之結果物件回報，其error不含args與env之值
  *
  * Unit Test: {@link https://github.com/yuda-lyu/wsemi/blob/master/test/execCliSession.test.mjs Github}
  * @memberOf wsemi
@@ -35,7 +36,7 @@ let { buildSpawnArgs, buildSpawnEnv } = execCliCore
  * @param {Function} [opt.onLine=undefined] 輸入stdout逐行回調函數，格式為(line)=>{}，line不含換行(\\r\\n與\\n皆視為換行)，子進程結束時殘餘之不完整行亦會發出，預設undefined
  * @param {Function} [opt.onStdout=undefined] 輸入stdout原始片段回調函數，格式為(chunk)=>{}，已經UTF-8跨chunk解碼，供非行式協定(如LSP之Content-Length分幀)自行分幀，預設undefined
  * @param {Function} [opt.onStderr=undefined] 輸入stderr片段回調函數，格式為(chunk)=>{}，預設undefined
- * @param {Function} [opt.onExit=undefined] 輸入子進程結束回調函數，格式為(result)=>{}，result同stop()之回傳，預設undefined
+ * @param {Function} [opt.onExit=undefined] 輸入子進程結束回調函數，格式為(result)=>{}，result同stop()之回傳，預設undefined。onLine、onStdout、onStderr、onExit內拋出之錯誤不會被攔截，將成為未捕捉例外，請於回調內自行處理
  * @returns {Object} 回傳工作階段物件s，內含pid(子進程pid，spawn失敗為null)、exited(是否已結束布林值)、write(str)(寫入stdin，回傳Promise，resolve為是否寫入成功布林值，子進程已結束時靜默resolve(false))、writeLine(str)(補換行後寫入)、stop()(關閉stdin並等待結束，回傳Promise，resolve回傳結果物件，內含code、signal、exited、timeout、killed、error、stderr、durationMs、pid；多次呼叫回傳同一Promise)
  * @example
  * //need test in nodejs
@@ -212,10 +213,10 @@ function execCliSession(command, args = [], opt = {}) {
         return s
     }
 
-    //spawn
-    let sp = buildSpawnArgs(command, args)
+    //spawn, buildSpawnArgs之拋錯亦於此回報
     let proc
     try {
+        let sp = buildSpawnArgs(command, args)
         proc = spawn(sp.file, sp.args, {
             cwd,
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -225,17 +226,33 @@ function execCliSession(command, args = [], opt = {}) {
         })
     }
     catch (err) {
-        //spawn同步拋錯(如參數無效EINVAL)
+        //spawn同步拋錯(如EPERM、ENAMETOOLONG、參數檢查錯誤), 訊息經execSpawnError去除參數值
+        let e = execSpawnError(err)
         s.write = async () => false
         s.writeLine = async () => false
         s.stop = stopNoProc
         setTimeout(() => {
-            settle({ error: `${err.code || 'UNKNOWN'}: ${err.message}` }) //待確認用err.toString()還是err.message更佳 bbb
+            settle({ error: `${e.code}: ${e.message}` })
         }, 1)
         return s
     }
     s.pid = proc.pid || null
 
+    //error, 須於存取stdio前監聽: node對EMFILE、ENFILE不建立stdio即於nextTick發出'error', 先存取會拋TypeError且'error'無人監聽而拉倒程序
+    //  可能為'找不到可執行檔'(ENOENT), '權限不足', '系統資源用盡'等, 訊息經execSpawnError去除參數值
+    proc.on('error', (err) => {
+        let e = execSpawnError(err)
+        settle({ error: `${e.code}: ${e.message}` })
+    })
+
+    //stdio, EMFILE、ENFILE時node未建立(undefined), 由上方error回報
+    if (!proc.stdout || !proc.stderr || !proc.stdin) {
+        s.write = async () => false
+        s.writeLine = async () => false
+        s.stop = stopNoProc
+        return s
+    }
+
     //TextDecoder, 跨chunk邊界正確解碼UTF-8, 避免多位元組中文字元被切成亂碼(U+FFFD)
     let stdoutDecoder = new TextDecoder('utf-8')
     let stderrDecoder = new TextDecoder('utf-8')
@@ -327,11 +344,6 @@ function execCliSession(command, args = [], opt = {}) {
         }, timeoutMs)
     }
 
-    //error, 監聽(例如執行spawn本身)錯誤訊息, 可能為'找不到可執行檔'(ENOENT), '權限不足', '系統資源用盡'等
-    proc.on('error', (err) => {
-        settle({ error: `${err.code || 'UNKNOWN'}: ${err.message}` }) //待確認用err.toString()還是err.message更佳 bbb
-    })
-
     //close
     proc.on('close', (code, signal) => {
         if (settled) {