'use strict';

const fs = require('node:fs');

/**
 * 將一行 `name=value` 附加寫入 GitHub/Gitea Action 的輸出檔。
 *
 * @param {string} name - 輸出變數名稱（output 的 key）。
 * @param {string} value - 輸出變數的值（output 的 value）。
 * @param {string} [file=process.env.GITHUB_OUTPUT] - 輸出檔路徑，預設取自環境變數 `GITHUB_OUTPUT`。
 * @throws {Error} 當輸出檔路徑為 falsy（例如 `GITHUB_OUTPUT` 未設定）時拋出，無法寫入輸出。
 * @returns {void}
 * @remarks 由 main 於計算出版本號後呼叫，將 `version` 寫入 Action output 供後續 step 取用；
 *   以 append 方式寫入、不覆蓋既有內容，且 value 僅支援單行字串（未處理換行或 `=`）。
 */
function writeOutput(name, value, file = process.env.GITHUB_OUTPUT) {
    if (!file) {
        throw new Error('GITHUB_OUTPUT 未設定，無法寫入輸出');
    }

    fs.appendFileSync(file, `${name}=${value}\n`);
}

module.exports = { writeOutput };