// 統一的主控台輸出格式,對應原本 entrypoint.sh 的 separator/section/info/... 等函式。

const LINE = '=================================================='
const SUBLINE = '--------------------------------------------------'

/**
 * 在前後換行的情況下輸出一條等號分隔線至 stdout,用於視覺上區隔不同階段的輸出。
 */
export function separator() {
  process.stdout.write(`\n${LINE}\n`)
}

/**
 * 輸出一個區段標題:先印分隔線,再印標題文字與一條虛線,用於標示流程進入新階段。
 * @param {string} title 區段標題文字
 */
export function section(title) {
  separator()
  process.stdout.write(`${title}\n`)
  process.stdout.write(`${SUBLINE}\n`)
}

/**
 * 以 `[INFO]` 前綴輸出一般資訊訊息至 stdout。
 * @param {string} message 訊息內容
 */
export function info(message) {
  process.stdout.write(`[INFO] ${message}\n`)
}

/**
 * 以 `[OK]` 前綴輸出成功訊息至 stdout(前綴補空白以與其他標籤對齊)。
 * @param {string} message 訊息內容
 */
export function success(message) {
  process.stdout.write(`[OK]   ${message}\n`)
}

/**
 * 以 `[WARN]` 前綴輸出警告訊息;為與一般輸出同流,仍寫入 stdout。
 * @param {string} message 訊息內容
 */
export function warn(message) {
  process.stdout.write(`[WARN] ${message}\n`)
}

/**
 * 以 `[ERR]` 前綴輸出錯誤訊息至 stderr(唯一寫入 stderr 的輸出函式)。
 * @param {string} message 訊息內容
 */
export function fail(message) {
  process.stderr.write(`[ERR]  ${message}\n`)
}

/**
 * 輸出錯誤至 stderr,並依錯誤型別保留可供除錯的上下文:
 * 若為 Error 物件,輸出「名稱: 訊息」並附上堆疊;否則輸出其字串形式。
 * 將「如何輸出錯誤」的邏輯集中於此,呼叫端毋須自行操作 stderr 或判斷型別。
 * @param {unknown} error 待輸出的錯誤
 */
export function failError(error) {
  if (error instanceof Error) {
    fail(`${error.name}: ${error.message}`)
    if (error.stack) {
      process.stderr.write(`${error.stack}\n`)
    }
  } else {
    fail(String(error))
  }
}