w-md2docx 1.0.6 → 1.0.7

package/docs/WMd2docx.mjs.html

@@ -88,7 +88,7 @@ export default WMd2docx
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 14:34:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 22:13:36 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/cvMdTo.mjs.html

@@ -275,7 +275,7 @@ export default cvMdTo
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 14:34:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 22:13:36 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/cvMdToDocx.mjs.html

@@ -54,7 +54,7 @@ import isobj from 'wsemi/src/isobj.mjs'
 import fsIsFile from 'wsemi/src/fsIsFile.mjs'
 import WMd2html from 'w-md2html/src/WMd2html.mjs'
 import WHtml2docx from 'w-html2docx/src/WHtml2docx.mjs'
-import { toErrText, retryBusy, runExclusive, getFpExe } from './utils.mjs'
+import { toErrText, retryBusy, runExclusive } from './utils.mjs'
 
 
 /**
@@ -62,7 +62,9 @@ import { toErrText, retryBusy, runExclusive, getFpExe } from './utils.mjs'
  *
  * 內部流程為md -> html -> docx。docx階段係調用本機Microsoft Word(win32com)，故僅能於已安裝Word之Windows執行，且同時間僅一份轉檔作業(內部佇列自動排隊)。
  *
- * 注意：底層w-html2docx於Word未安裝或COM呼叫失敗時「仍回傳ok」，本函數一律以產物實體檔之存在與大小驗證成敗，失敗即reject，不會回報假成功。
+ * 轉檔器htmlToDocx.exe之定位與補齊由w-html2docx負責：其以當前工作目錄(cwd)查找，缺檔(如npm封鎖安裝腳本致postinstall未執行)時於轉檔當下自動下載，故須於含node_modules/w-html2docx之專案根執行，且首次轉檔須可連網。
+ *
+ * w-html2docx(≥1.0.29)於轉檔器失敗(Word未安裝、模板無法開啟、另存失敗等)時以離開碼1 reject並帶轉檔器回報之原因，resolve前亦自行確認docx已產生；本函數將其訊息加上前綴原樣傳出，並再以產物實體檔之存在與大小把關一次，不會回報假成功。
  *
  * @param {String} fpInMd 輸入來源Markdown檔位置字串
  * @param {String} fpOutDocx 輸入轉出Docx檔位置字串
@@ -160,13 +162,9 @@ async function cvMdToDocx(fpInMd, fpOutDocx, opt = {}) {
         }
         let sizeHtml = fs.statSync(fpOutHtml).size
 
-        //事前檢查轉檔器(依 cwd 定位, 查無則此 cwd 下必定失敗, 先行明確報錯)
-        let fpExe = getFpExe()
-        if (fpExe === '') {
-            return Promise.reject(`htmlToDocx.exe not found (cwd=${path.resolve()}), please run from the folder that contains node_modules/w-html2docx`)
-        }
-
         //html -> docx(排隊逐一執行, 避免同時調用本機 Word)
+        //note: 轉檔器之定位與缺檔下載由 WHtml2docx 內部 autoDownloadFiles 負責, 此處不得事前檢查,
+        //      否則下層之自動補齊永遠不會被執行
         fs.mkdirSync(path.dirname(fpOutDocx), { recursive: true })
         let errDocx = null
         await runExclusive(() => retryBusy(() => WHtml2docx(fpOutHtml, fpOutDocx, optHtml2docx)))
@@ -174,12 +172,16 @@ async function cvMdToDocx(fpInMd, fpOutDocx, opt = {}) {
                 errDocx = toErrText(err)
             })
         if (errDocx !== null) {
+            //w-html2docx 以 cwd 查找 htmlToDocx.exe 與預設模板, 查找失敗之訊息含 can not find, 保留原文並補上 cwd 與執行位置提示
+            if (errDocx.indexOf('can not find') >= 0) {
+                errDocx = `${errDocx} (cwd=${path.resolve()}, w-html2docx resolves htmlToDocx.exe and its default template from cwd and downloads htmlToDocx.exe automatically when absent, please run from the project root that contains node_modules/w-html2docx)`
+            }
             return Promise.reject(`Failed to convert html to docx: ${errDocx}`)
         }
 
-        //驗證 docx
-        //why: w-html2docx 於 Word 未安裝、COM 呼叫失敗等情形「仍回傳 ok」(錯誤僅印於其子程序之輸出),
-        //     故一律以產物實體檔之存在與大小為準, 否則將回報假成功
+        //驗證 docx(第二道防線)
+        //note: w-html2docx ≥1.0.29 於轉檔器失敗時已自行 reject(離開碼1, 帶轉檔器原因), resolve 前亦確認 docx 已產生且非空,
+        //      此處再以產物實體檔為準把關一次, 涵蓋其 resolve 後檔案又消失等非預期情形, 不憑回傳值
         if (!fsIsFile(fpOutDocx) || fs.statSync(fpOutDocx).size === 0) {
             return Promise.reject('docx was not generated: please make sure Microsoft Word is installed and no stale WINWORD process is locking the files')
         }
@@ -230,7 +232,7 @@ export default cvMdToDocx
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 14:34:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 22:13:36 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/global.html

@@ -222,14 +222,15 @@ console.log(r)
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>檢查本機是否具備docx轉檔條件(Windows且轉檔器存在)</p>
-<p>注意：僅代表環境條件成立，不代表Word確實可被調用；後者須實際轉一份小檔驗證。</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>檢查本機是否具備docx轉檔條件</p>
+<p>ready僅以作業系統為Windows判定，不以轉檔器是否存在為條件：exeFound為false代表轉檔器目前尚未取得，將於首次轉檔時由w-html2docx自動下載，並非不可用。</p>
+<p>注意：僅代表環境條件成立，不代表轉檔器可下載成功或Word確實可被調用；後二者須實際轉一份小檔驗證。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line205">line 205</a>
+        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line209">line 209</a>
     </li></ul></dd>
     
 
@@ -277,7 +278,7 @@ console.log(r)
     <h5 class="h5-examples">Example</h5>
     
     <pre class="prettyprint"><code>console.log(checkDocxReady())
-// => { platform: 'win32', isWindows: true, cwd: '...', exePath: '...', exeFound: true, ready: true }</code></pre>
+// => { platform: 'win32', isWindows: true, cwd: '...', exePath: '', exeFound: false, ready: true }</code></pre>
 
 
 
@@ -300,7 +301,7 @@ console.log(r)
 
         
 <div class="param-desc">
-    <p>回傳狀態物件{platform,isWindows,cwd,exePath,exeFound,ready}</p>
+    <p>回傳狀態物件{platform,isWindows,cwd,exePath,exeFound,ready}，exePath與exeFound為轉檔器目前所在位置與是否已存在(診斷用)</p>
 </div>
 
 
@@ -344,7 +345,7 @@ console.log(r)
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line369">line 369</a>
+        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line374">line 374</a>
     </li></ul></dd>
     
 
@@ -2068,13 +2069,14 @@ console.log(r)
     <dt class="tag-description">Description:</dt>
     <dd class="tag-description"><ul class="dummy"><li><p>Markdown檔轉Docx檔</p>
 <p>內部流程為md -&gt; html -&gt; docx。docx階段係調用本機Microsoft Word(win32com)，故僅能於已安裝Word之Windows執行，且同時間僅一份轉檔作業(內部佇列自動排隊)。</p>
-<p>注意：底層w-html2docx於Word未安裝或COM呼叫失敗時「仍回傳ok」，本函數一律以產物實體檔之存在與大小驗證成敗，失敗即reject，不會回報假成功。</p></li></ul></dd>
+<p>轉檔器htmlToDocx.exe之定位與補齊由w-html2docx負責：其以當前工作目錄(cwd)查找，缺檔(如npm封鎖安裝腳本致postinstall未執行)時於轉檔當下自動下載，故須於含node_modules/w-html2docx之專案根執行，且首次轉檔須可連網。</p>
+<p>w-html2docx(≥1.0.29)於轉檔器失敗(Word未安裝、模板無法開啟、另存失敗等)時以離開碼1 reject並帶轉檔器回報之原因，resolve前亦自行確認docx已產生；本函數將其訊息加上前綴原樣傳出，並再以產物實體檔之存在與大小把關一次，不會回報假成功。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="cvMdToDocx.mjs.html">cvMdToDocx.mjs</a>, <a href="cvMdToDocx.mjs.html#line42">line 42</a>
+        <a href="cvMdToDocx.mjs.html">cvMdToDocx.mjs</a>, <a href="cvMdToDocx.mjs.html#line44">line 44</a>
     </li></ul></dd>
     
 
@@ -2522,14 +2524,15 @@ console.log(r)
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>取w-html2docx之htmlToDocx.exe位置</p>
-<p>注意：w-html2docx內部以「模組載入當下之工作目錄(cwd)」推導exe位置，故此處以同一規則檢查，使事前檢查與實際轉檔行為一致；查無即代表由此cwd執行必定轉檔失敗。</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>取w-html2docx之htmlToDocx.exe目前所在位置(僅供診斷顯示)</p>
+<p>依w-html2docx之查找位置(cwd之src/、cwd之node_modules/w-html2docx/src/)查詢檔案「目前」是否存在，不下載。</p>
+<p>注意：不得作為轉檔前之守門。查無不代表無法轉檔——w-html2docx於轉檔當下會自動下載缺少之轉檔器，上層以此攔截會使該機制永遠不被執行。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line178">line 178</a>
+        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line180">line 180</a>
     </li></ul></dd>
     
 
@@ -2600,7 +2603,7 @@ console.log(r)
 
         
 <div class="param-desc">
-    <p>回傳exe位置字串，查無則回傳空字串</p>
+    <p>回傳exe位置字串，目前不存在則回傳空字串</p>
 </div>
 
 
@@ -3364,7 +3367,7 @@ console.log(r)
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line288">line 288</a>
+        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line293">line 293</a>
     </li></ul></dd>
     
 
@@ -4920,7 +4923,7 @@ console.log(toErrText(new Error('abc')))
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line234">line 234</a>
+        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line239">line 239</a>
     </li></ul></dd>
     
 
@@ -5088,7 +5091,7 @@ console.log(toSafeName(''))
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line422">line 422</a>
+        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line427">line 427</a>
     </li></ul></dd>
     
 
@@ -5253,7 +5256,7 @@ console.log(toSafeName(''))
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line327">line 327</a>
+        <a href="utils.mjs.html">utils.mjs</a>, <a href="utils.mjs.html#line332">line 332</a>
     </li></ul></dd>
     
 
@@ -5440,7 +5443,7 @@ console.log(toSafeName(''))
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 14:34:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 22:13:36 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 14:34:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 22:13:36 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/rmApiClient.mjs.html

@@ -526,7 +526,7 @@ export default rmApiClient
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 14:34:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 22:13:36 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/rmApiServer.mjs.html

@@ -253,9 +253,9 @@ async function rmApiServer(opt = {}) {
             platform: rd.platform,
             node: process.version,
             cwd: rd.cwd,
-            exeFound: rd.exeFound,
+            exeFound: rd.exeFound, //轉檔器目前是否已存在(診斷用), false 時於首次轉檔由 w-html2docx 自動下載
             exePath: rd.exePath,
-            docxReady: rd.ready, //僅代表環境具備條件, 實際 Word 可用性須以 /api/selftest 驗證
+            docxReady: rd.ready, //僅代表環境具備條件, 轉檔器可否下載與 Word 可用性須以 /api/selftest 實轉驗證
             templateDefault: getFpTemplateDef(),
             templates: listTemplates(),
             dirTemplates,
@@ -503,7 +503,7 @@ export default rmApiServer
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 14:34:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 22:13:36 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/utils.mjs.html

@@ -211,11 +211,13 @@ function getQueueSize() {
 
 
 /**
- * 取w-html2docx之htmlToDocx.exe位置
+ * 取w-html2docx之htmlToDocx.exe目前所在位置(僅供診斷顯示)
  *
- * 注意：w-html2docx內部以「模組載入當下之工作目錄(cwd)」推導exe位置，故此處以同一規則檢查，使事前檢查與實際轉檔行為一致；查無即代表由此cwd執行必定轉檔失敗。
+ * 依w-html2docx之查找位置(cwd之src/、cwd之node_modules/w-html2docx/src/)查詢檔案「目前」是否存在，不下載。
  *
- * @returns {String} 回傳exe位置字串，查無則回傳空字串
+ * 注意：不得作為轉檔前之守門。查無不代表無法轉檔——w-html2docx於轉檔當下會自動下載缺少之轉檔器，上層以此攔截會使該機制永遠不被執行。
+ *
+ * @returns {String} 回傳exe位置字串，目前不存在則回傳空字串
  * @example
  *
  * console.log(getFpExe())
@@ -238,26 +240,29 @@ function getFpExe() {
 
 
 /**
- * 檢查本機是否具備docx轉檔條件(Windows且轉檔器存在)
+ * 檢查本機是否具備docx轉檔條件
+ *
+ * ready僅以作業系統為Windows判定，不以轉檔器是否存在為條件：exeFound為false代表轉檔器目前尚未取得，將於首次轉檔時由w-html2docx自動下載，並非不可用。
  *
- * 注意：僅代表環境條件成立，不代表Word確實可被調用；後者須實際轉一份小檔驗證。
+ * 注意：僅代表環境條件成立，不代表轉檔器可下載成功或Word確實可被調用；後二者須實際轉一份小檔驗證。
  *
- * @returns {Object} 回傳狀態物件{platform,isWindows,cwd,exePath,exeFound,ready}
+ * @returns {Object} 回傳狀態物件{platform,isWindows,cwd,exePath,exeFound,ready}，exePath與exeFound為轉檔器目前所在位置與是否已存在(診斷用)
  * @example
  *
  * console.log(checkDocxReady())
- * // => { platform: 'win32', isWindows: true, cwd: '...', exePath: '...', exeFound: true, ready: true }
+ * // => { platform: 'win32', isWindows: true, cwd: '...', exePath: '', exeFound: false, ready: true }
  *
  */
 function checkDocxReady() {
     let fpExe = getFpExe()
+    let isWindows = process.platform === 'win32'
     return {
         platform: process.platform,
-        isWindows: process.platform === 'win32',
+        isWindows,
         cwd: path.resolve(),
         exePath: fpExe,
         exeFound: fpExe !== '',
-        ready: process.platform === 'win32' && fpExe !== '',
+        ready: isWindows,
     }
 }
 
@@ -507,7 +512,7 @@ export {
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 14:34:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Sep 13 2026 22:13:36 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "w-md2docx",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "main": "dist/w-md2docx.umd.js",
   "dependencies": {
     "@hapi/hapi": "^21.4.10",
-    "w-html2docx": "^1.0.28",
+    "w-html2docx": "^1.0.29",
     "w-md2html": "^1.0.51",
-    "wsemi": "^1.8.92"
+    "wsemi": "^1.8.93"
   },
   "devDependencies": {
     "w-package-tools": "^1.1.16"

package/src/cvMdToDocx.mjs

@@ -7,7 +7,7 @@ import isobj from 'wsemi/src/isobj.mjs'
 import fsIsFile from 'wsemi/src/fsIsFile.mjs'
 import WMd2html from 'w-md2html/src/WMd2html.mjs'
 import WHtml2docx from 'w-html2docx/src/WHtml2docx.mjs'
-import { toErrText, retryBusy, runExclusive, getFpExe } from './utils.mjs'
+import { toErrText, retryBusy, runExclusive } from './utils.mjs'
 
 
 /**
@@ -15,7 +15,9 @@ import { toErrText, retryBusy, runExclusive, getFpExe } from './utils.mjs'
  *
  * 內部流程為md -> html -> docx。docx階段係調用本機Microsoft Word(win32com)，故僅能於已安裝Word之Windows執行，且同時間僅一份轉檔作業(內部佇列自動排隊)。
  *
- * 注意：底層w-html2docx於Word未安裝或COM呼叫失敗時「仍回傳ok」，本函數一律以產物實體檔之存在與大小驗證成敗，失敗即reject，不會回報假成功。
+ * 轉檔器htmlToDocx.exe之定位與補齊由w-html2docx負責：其以當前工作目錄(cwd)查找，缺檔(如npm封鎖安裝腳本致postinstall未執行)時於轉檔當下自動下載，故須於含node_modules/w-html2docx之專案根執行，且首次轉檔須可連網。
+ *
+ * w-html2docx(≥1.0.29)於轉檔器失敗(Word未安裝、模板無法開啟、另存失敗等)時以離開碼1 reject並帶轉檔器回報之原因，resolve前亦自行確認docx已產生；本函數將其訊息加上前綴原樣傳出，並再以產物實體檔之存在與大小把關一次，不會回報假成功。
  *
  * @param {String} fpInMd 輸入來源Markdown檔位置字串
  * @param {String} fpOutDocx 輸入轉出Docx檔位置字串
@@ -113,13 +115,9 @@ async function cvMdToDocx(fpInMd, fpOutDocx, opt = {}) {
         }
         let sizeHtml = fs.statSync(fpOutHtml).size
 
-        //事前檢查轉檔器(依 cwd 定位, 查無則此 cwd 下必定失敗, 先行明確報錯)
-        let fpExe = getFpExe()
-        if (fpExe === '') {
-            return Promise.reject(`htmlToDocx.exe not found (cwd=${path.resolve()}), please run from the folder that contains node_modules/w-html2docx`)
-        }
-
         //html -> docx(排隊逐一執行, 避免同時調用本機 Word)
+        //note: 轉檔器之定位與缺檔下載由 WHtml2docx 內部 autoDownloadFiles 負責, 此處不得事前檢查,
+        //      否則下層之自動補齊永遠不會被執行
         fs.mkdirSync(path.dirname(fpOutDocx), { recursive: true })
         let errDocx = null
         await runExclusive(() => retryBusy(() => WHtml2docx(fpOutHtml, fpOutDocx, optHtml2docx)))
@@ -127,12 +125,16 @@ async function cvMdToDocx(fpInMd, fpOutDocx, opt = {}) {
                 errDocx = toErrText(err)
             })
         if (errDocx !== null) {
+            //w-html2docx 以 cwd 查找 htmlToDocx.exe 與預設模板, 查找失敗之訊息含 can not find, 保留原文並補上 cwd 與執行位置提示
+            if (errDocx.indexOf('can not find') >= 0) {
+                errDocx = `${errDocx} (cwd=${path.resolve()}, w-html2docx resolves htmlToDocx.exe and its default template from cwd and downloads htmlToDocx.exe automatically when absent, please run from the project root that contains node_modules/w-html2docx)`
+            }
             return Promise.reject(`Failed to convert html to docx: ${errDocx}`)
         }
 
-        //驗證 docx
-        //why: w-html2docx 於 Word 未安裝、COM 呼叫失敗等情形「仍回傳 ok」(錯誤僅印於其子程序之輸出),
-        //     故一律以產物實體檔之存在與大小為準, 否則將回報假成功
+        //驗證 docx(第二道防線)
+        //note: w-html2docx ≥1.0.29 於轉檔器失敗時已自行 reject(離開碼1, 帶轉檔器原因), resolve 前亦確認 docx 已產生且非空,
+        //      此處再以產物實體檔為準把關一次, 涵蓋其 resolve 後檔案又消失等非預期情形, 不憑回傳值
         if (!fsIsFile(fpOutDocx) || fs.statSync(fpOutDocx).size === 0) {
             return Promise.reject('docx was not generated: please make sure Microsoft Word is installed and no stale WINWORD process is locking the files')
         }

package/src/rmApiServer.mjs

@@ -206,9 +206,9 @@ async function rmApiServer(opt = {}) {
             platform: rd.platform,
             node: process.version,
             cwd: rd.cwd,
-            exeFound: rd.exeFound,
+            exeFound: rd.exeFound, //轉檔器目前是否已存在(診斷用), false 時於首次轉檔由 w-html2docx 自動下載
             exePath: rd.exePath,
-            docxReady: rd.ready, //僅代表環境具備條件, 實際 Word 可用性須以 /api/selftest 驗證
+            docxReady: rd.ready, //僅代表環境具備條件, 轉檔器可否下載與 Word 可用性須以 /api/selftest 實轉驗證
             templateDefault: getFpTemplateDef(),
             templates: listTemplates(),
             dirTemplates,

package/src/utils.mjs

@@ -164,11 +164,13 @@ function getQueueSize() {
 
 
 /**
- * 取w-html2docx之htmlToDocx.exe位置
+ * 取w-html2docx之htmlToDocx.exe目前所在位置(僅供診斷顯示)
  *
- * 注意：w-html2docx內部以「模組載入當下之工作目錄(cwd)」推導exe位置，故此處以同一規則檢查，使事前檢查與實際轉檔行為一致；查無即代表由此cwd執行必定轉檔失敗。
+ * 依w-html2docx之查找位置(cwd之src/、cwd之node_modules/w-html2docx/src/)查詢檔案「目前」是否存在，不下載。
  *
- * @returns {String} 回傳exe位置字串，查無則回傳空字串
+ * 注意：不得作為轉檔前之守門。查無不代表無法轉檔——w-html2docx於轉檔當下會自動下載缺少之轉檔器，上層以此攔截會使該機制永遠不被執行。
+ *
+ * @returns {String} 回傳exe位置字串，目前不存在則回傳空字串
  * @example
  *
  * console.log(getFpExe())
@@ -191,26 +193,29 @@ function getFpExe() {
 
 
 /**
- * 檢查本機是否具備docx轉檔條件(Windows且轉檔器存在)
+ * 檢查本機是否具備docx轉檔條件
+ *
+ * ready僅以作業系統為Windows判定，不以轉檔器是否存在為條件：exeFound為false代表轉檔器目前尚未取得，將於首次轉檔時由w-html2docx自動下載，並非不可用。
  *
- * 注意：僅代表環境條件成立，不代表Word確實可被調用；後者須實際轉一份小檔驗證。
+ * 注意：僅代表環境條件成立，不代表轉檔器可下載成功或Word確實可被調用；後二者須實際轉一份小檔驗證。
  *
- * @returns {Object} 回傳狀態物件{platform,isWindows,cwd,exePath,exeFound,ready}
+ * @returns {Object} 回傳狀態物件{platform,isWindows,cwd,exePath,exeFound,ready}，exePath與exeFound為轉檔器目前所在位置與是否已存在(診斷用)
  * @example
  *
  * console.log(checkDocxReady())
- * // => { platform: 'win32', isWindows: true, cwd: '...', exePath: '...', exeFound: true, ready: true }
+ * // => { platform: 'win32', isWindows: true, cwd: '...', exePath: '', exeFound: false, ready: true }
  *
  */
 function checkDocxReady() {
     let fpExe = getFpExe()
+    let isWindows = process.platform === 'win32'
     return {
         platform: process.platform,
-        isWindows: process.platform === 'win32',
+        isWindows,
         cwd: path.resolve(),
         exePath: fpExe,
         exeFound: fpExe !== '',
-        ready: process.platform === 'win32' && fpExe !== '',
+        ready: isWindows,
     }
 }
 

package/test/api-rmApiClient.test.mjs

@@ -7,6 +7,32 @@ import rmApiClient, { cvMdTo, health, scanAssetPaths, readAssets } from '../src/
 
 describe('rmApiClient', function() {
 
+    let fdTmpRoot = path.resolve('./test/_tmp/api-rmApiClient')
+
+    after(function() {
+        fs.rmSync(fdTmpRoot, { recursive: true, force: true, maxRetries: 10, retryDelay: 300 })
+    })
+
+    //withoutEnv: 暫時移除服務位置之環境變數後執行, 使預設值測試不受執行環境影響
+    let withoutEnv = async (fun) => {
+        let keys = ['WMD2DOCX_URL', 'WMD2DOCX_HOST', 'WMD2DOCX_PORT']
+        let kp = {}
+        for (let k of keys) {
+            kp[k] = process.env[k]
+            delete process.env[k]
+        }
+        try {
+            return await fun()
+        }
+        finally {
+            for (let k of keys) {
+                if (kp[k] !== undefined) {
+                    process.env[k] = kp[k]
+                }
+            }
+        }
+    }
+
     describe('scanAssetPaths(純函數)', function() {
 
         it('涵蓋<img src>與![]() , 去重, 保留原字串', function() {
@@ -48,7 +74,7 @@ describe('rmApiClient', function() {
 
     describe('readAssets(讀本機檔)', function() {
 
-        let fdTmp = path.resolve('./tmp/zt_rmApiClient_ra')
+        let fdTmp = path.resolve(fdTmpRoot, 'readAssets')
 
         before(function() {
             fs.mkdirSync(path.resolve(fdTmp, 'pics'), { recursive: true })
@@ -56,10 +82,6 @@ describe('rmApiClient', function() {
             fs.writeFileSync(path.resolve(fdTmp, 'pics/a b.png'), 'IMG2')
         })
 
-        after(function() {
-            fs.rmSync(fdTmp, { recursive: true, force: true })
-        })
-
         it('URL編碼引用可對應解碼後實體檔, path保留原字串', function() {
             let { assets, missing } = readAssets('![p](pics/%E5%9C%96.png)\n<img src="pics/a%20b.png">', fdTmp)
             assert.strict.deepEqual(missing, [])
@@ -83,27 +105,25 @@ describe('rmApiClient', function() {
 
     describe('cvMdTo/health(對接rmApiServer, html路徑不需Word)', function() {
 
-        let fdTmp = path.resolve('./tmp/zt_rmApiClient')
+        let fdTmp = path.resolve(fdTmpRoot, 'service')
         let dirWork = path.resolve(fdTmp, 'work')
         let token = 'tk-client'
         let srv = null
         let host = '127.0.0.1'
-        let port = 0
-        let url = ''
+        let port = 8211 //固定埠(8000以上), 與api-rmApiServer(8201, 8202)錯開以免並行撞埠
+        let url = `http://${host}:${port}`
+        let hostInvalid = 'nonexistent.invalid' //.invalid為保留網域(RFC 2606)必定解析失敗, 使預設埠之驗證不受本機22000埠是否有服務影響
         let fpOutHtml = path.resolve(fdTmp, 'out/report.html')
 
         before(async function() {
             fs.mkdirSync(fdTmp, { recursive: true })
-            srv = await rmApiServer({ port: 0, host, token, dirWork })
-            port = srv.server.info.port
-            url = `http://${host}:${port}`
+            srv = await rmApiServer({ port, host, token, dirWork })
         })
 
         after(async function() {
             if (srv) {
                 await srv.stop()
             }
-            fs.rmSync(fdTmp, { recursive: true, force: true })
         })
 
         it('default export匯整四函數', function() {
@@ -131,12 +151,17 @@ describe('rmApiClient', function() {
             }
         })
 
-        it('host/port與環境變數皆未給時預設127.0.0.1:22000(與rmApiServer預設埠一致)', async function() {
-            await assert.rejects(health({ token, timeoutMs: 3000 }), (e) => /^Unable to connect to the conversion service http:\/\/127\.0\.0\.1:22000: /.test(e) || /^Invalid response from the conversion service http:\/\/127\.0\.0\.1:22000/.test(e))
+        it('host與環境變數皆未給時預設127.0.0.1', async function() {
+            let r = await withoutEnv(() => health({ port, token })) //僅給port, 須連到127.0.0.1上之測試服務
+            assert.strict.equal(r.success, true)
+        })
+
+        it('port與環境變數皆未給時預設22000(與rmApiServer預設埠一致)', async function() {
+            await withoutEnv(() => assert.rejects(health({ host: hostInvalid, token, timeoutMs: 3000 }), (e) => String(e).startsWith(`Unable to connect to the conversion service http://${hostInvalid}:22000: `)))
         })
 
         it('port非正整數視為未給', async function() {
-            await assert.rejects(health({ host, port: 'x', token, timeoutMs: 3000 }), (e) => /http:\/\/127\.0\.0\.1:22000/.test(e))
+            await withoutEnv(() => assert.rejects(health({ host: hostInvalid, port: 'x', token, timeoutMs: 3000 }), (e) => String(e).startsWith(`Unable to connect to the conversion service http://${hostInvalid}:22000: `)))
         })
 
         it('url給予時覆寫host/port', async function() {

package/test/api-rmApiServer.test.mjs

@@ -7,10 +7,12 @@ import rmApiServer from '../src/rmApiServer.mjs'
 //rmApiServer: 直打HTTP端點(不經UI); docx相關以html路徵替代, 不需Word
 describe('rmApiServer', function() {
 
-    let fdTmp = path.resolve('./tmp/zt_rmApiServer')
+    let fdTmp = path.resolve('./test/_tmp/api-rmApiServer')
     let dirWork = path.resolve(fdTmp, 'work')
     let token = 'tk-test'
     let svgB64 = fs.readFileSync('./test/cocktail.svg').toString('base64')
+    let portMain = 8201 //固定埠(8000以上), 與api-rmApiClient(8211)錯開以免並行撞埠
+    let portStop = 8202
     let srv = null
     let url = ''
 
@@ -24,19 +26,20 @@ describe('rmApiServer', function() {
 
     before(async function() {
         fs.mkdirSync(fdTmp, { recursive: true })
-        srv = await rmApiServer({ port: 0, host: '127.0.0.1', token, dirWork }) //port 0 由系統配置, 避免並行測試撞埠
-        url = `http://127.0.0.1:${srv.server.info.port}`
+        srv = await rmApiServer({ port: portMain, host: '127.0.0.1', token, dirWork })
+        url = `http://127.0.0.1:${portMain}`
     })
 
     after(async function() {
         if (srv) {
             await srv.stop()
         }
-        fs.rmSync(fdTmp, { recursive: true, force: true })
+        fs.rmSync(fdTmp, { recursive: true, force: true, maxRetries: 10, retryDelay: 300 })
     })
 
     it('回傳物件與settings', function() {
-        assert.strict.equal(typeof srv.server.info.port, 'number')
+        assert.strict.equal(srv.server.info.port, portMain)
+        assert.strict.equal(srv.settings.port, portMain)
         assert.strict.equal(typeof srv.getState, 'function')
         assert.strict.equal(typeof srv.stop, 'function')
         assert.strict.equal(srv.settings.host, '127.0.0.1')
@@ -180,8 +183,8 @@ describe('rmApiServer', function() {
     })
 
     it('stop後不再回應', async function() {
-        let s3 = await rmApiServer({ port: 0, host: '127.0.0.1', dirWork: path.resolve(fdTmp, 'work3') })
-        let u3 = `http://127.0.0.1:${s3.server.info.port}`
+        let s3 = await rmApiServer({ port: portStop, host: '127.0.0.1', dirWork: path.resolve(fdTmp, 'work3') })
+        let u3 = `http://127.0.0.1:${portStop}`
         let res = await fetch(`${u3}/api/health`)
         assert.strict.equal(res.status, 200) //無token時不需標頭
         await s3.stop()