README.md

@@ -1,6 +1,6 @@
 # calculate-version
 
-> 更新時間：2026/06/26 10:37:28
+> 更新時間：2026/06/26 10:49:46
 
 計算版本號的 Gitea Action。依現有 release 推算下一個穩定版或 beta 版本號，並將結果寫入 Action output `version`。核心邏輯以 Node.js 實作，置於 `app/`，由 `entrypoint.sh` 作為容器進入點啟動。
 
@@ -12,7 +12,7 @@
 
 | 專案名稱 | 專案描述 |
 | --- | --- |
-| [calculate-version](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app) | 計算版本號的 Gitea Action：載入環境設定、分頁抓取 Gitea release、計算下一個穩定版或 beta 版本號，並寫出 Action output。 |
+| [calculate-version](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app) | 計算版本號的 Gitea Action：載入並驗證環境設定、分頁抓取 Gitea release、計算下一個穩定版或 beta 版本號，並寫出 Action output。 |
 
 ### 參考專案
 
@@ -28,13 +28,19 @@
 
 ## 功能列表
 
+### index（app/index.js）
+
+| 功能名稱 | 功能描述 |
+| --- | --- |
+| [index.main](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/index.js#L23) | [Action 進入點：協調設定載入、release 取得、版本計算與輸出（支援相依注入）。](#indexmain) |
+
 ### logger（app/logger.js）
 
 | 功能名稱 | 功能描述 |
 | --- | --- |
 | [logger.section](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L16) | [輸出帶標題的區塊段落至標準輸出，標題前後以分隔線包夾。](#loggersection) |
 | [logger.info](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L26) | [輸出一般資訊層級的 log 訊息，自動加上 `[info]` 前綴。](#loggerinfo) |
-| [logger.fail](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L40) | [輸出錯誤訊息至 stderr 並以狀態碼 1 終止行程。](#loggerfail) |
+| [logger.error](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L38) | [輸出錯誤訊息至 stderr（僅輸出，不終止行程）。](#loggererror) |
 
 ### config（app/config.js）
 
@@ -43,7 +49,7 @@
 | [config.isUnset](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L11) | [判斷環境變數值是否視為「未設定」。](#configisunset) |
 | [config.requireEnv](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L23) | [驗證必填環境變數，未設定時拋出錯誤。](#configrequireenv) |
 | [config.normalizeBetaFlag](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L38) | [將 beta 旗標正規化為布林值。](#confignormalizebetaflag) |
-| [config.loadConfig](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L55) | [從環境變數載入並驗證執行所需的設定。](#configloadconfig) |
+| [config.loadConfig](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L68) | [從環境變數載入並驗證執行所需的設定。](#configloadconfig) |
 
 ### version（app/version.js）
 
@@ -70,6 +76,24 @@
 
 ## 使用範例
 
+<a id="indexmain"></a>
+### index.main
+
+Action 進入點：依序協調設定載入、release 取得、版本計算與輸出寫出，回傳計算出的版本號。失敗時向外拋出例外（由進入點頂層攔截並以狀態碼 1 結束）。相依模組可透過 `deps` 注入，便於測試。模組僅在被直接執行（`node app/index.js`）時自動啟動。
+
+```js
+const { main } = require('./index');
+
+// 測試或自訂情境：注入假的相依
+const version = await main({
+  loadConfig: () => ({ serverUrl: 'https://gitea.example.com', repository: 'owner/repo', token: null, isBeta: false }),
+  fetchReleases: async () => ([{ tag_name: 'v1.2.3' }]),
+  writeOutput: () => {},
+  log: { section() {}, info() {}, error() {} },
+});
+// version === '1.2.4'
+```
+
 <a id="loggersection"></a>
 ### logger.section
 
@@ -98,17 +122,16 @@ logger.info('IS_BETA=false');
 // 輸出：[info] IS_BETA=false
 ```
 
-<a id="loggerfail"></a>
+<a id="loggererror"></a>
-### logger.fail
+### logger.error
 
-輸出錯誤訊息至標準錯誤輸出（stderr），並以狀態碼 1 立即終止整個行程。用於發生無法復原的錯誤時中止執行；呼叫後其下程式碼不會執行。
+輸出錯誤訊息至標準錯誤輸出（stderr），自動加上 `[error]` 前綴與換行。僅負責輸出，**不終止行程**；是否結束由呼叫端（進入點）決定，以利測試與錯誤復原。
 
 ```js
 const logger = require('./logger');
 
-logger.fail('GITEA_SERVER_URL 未設定');
+logger.error('GITEA_SERVER_URL 未設定');
 // 對 stderr 輸出：[error] GITEA_SERVER_URL 未設定
-// 接著 process.exit(1) 終止行程
 ```
 
 <a id="configisunset"></a>
@@ -152,7 +175,7 @@ normalizeBetaFlag(undefined); // false
 <a id="configloadconfig"></a>
 ### config.loadConfig
 
-從環境變數載入並驗證執行所需的設定。`GITEA_SERVER_URL` 與 `GITEA_REPOSITORY` 為必填（未設定即拋錯）；`GITEA_TOKEN` 非必填（未設定為 `null`）；`IS_BETA` 會正規化為布林值。
+從環境變數載入並驗證執行所需的設定。`GITEA_SERVER_URL` 與 `GITEA_REPOSITORY` 為必填（未設定即拋錯），且 `GITEA_SERVER_URL` 須為合法的 http/https URL；`GITEA_TOKEN` 非必填（未設定為 `null`）；`IS_BETA` 會正規化為布林值。
 
 ```js
 const { loadConfig } = require('./config');
@@ -248,7 +271,7 @@ calculateVersion([{ tag_name: 'v1.2.3' }], true);
 <a id="releasesfetchreleases"></a>
 ### releases.fetchReleases
 
-以分頁方式取得指定 Gitea repo 的所有 release，並回傳合併後的陣列。使用全域 `fetch` 逐頁請求（每頁 limit 為 10）；當某頁回傳空資料、`null` 或筆數少於上限時即停止。提供 `options.token` 時以授權方式請求。網路失敗、非 2xx、無法解析或非陣列回應時拋出 `Error`。
+以分頁方式取得指定 Gitea repo 的所有 release，並回傳合併後的陣列。使用全域 `fetch` 逐頁請求（每頁 limit 為 10）；當某頁回傳空資料、`null` 或筆數少於上限時即停止。提供 `options.token` 時以授權方式請求。網路失敗、回應讀取失敗、非 2xx、無法解析或非陣列回應時拋出 `Error`（含頁碼）。
 
 ```js
 const { fetchReleases } = require('./releases');