依功能分組為 logger/validate/config/gitea-client/releases/tags 模組,
entrypoint.sh 改為呼叫 node /app/index.js,Dockerfile 改用 node:20-alpine 基底。
對外行為(清理舊 release 與未指定 release 的 tag)維持不變。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@@ -5,1 +10,4 @@
 
+# 複製 Node.js 應用程式(不含測試)
+# 先單獨複製 package.json,再複製所有 *.js;有利於 Docker layer 快取。
+COPY app/package.json /app/package.json

@@ -6,0 +13,4 @@
+COPY app/package.json /app/package.json
+COPY app/*.js /app/
+
+# 複製容器進入點腳本至根目錄。

@@ -0,0 +8,4 @@
+ * 從環境變數載入設定並完成驗證。
+ * @param {NodeJS.ProcessEnv} env 環境變數來源,預設為 process.env
+ * @returns 包含 API 位址、token、保留數量等資訊的設定物件
+ */

@@ -0,0 +18,4 @@
+  const token = env.GITEA_TOKEN
+
+  info(`GITEA_SERVER_URL=${serverUrl}`)
+  requireValue('GITEA_SERVER_URL', serverUrl)

@@ -0,0 +28,4 @@
+  requireInteger('KEEP_COUNT', keepCountRaw)
+
+  if (isEmptyOrNull(token)) {
+    warn('GITEA_TOKEN is empty; release API calls will be anonymous')

@@ -0,0 +36,4 @@
+  return {
+    serverUrl,
+    repository,
+    token: isEmptyOrNull(token) ? null : token,

@@ -0,0 +22,4 @@
+    let page = 1
+
+    while (true) {
+      const url = `${baseUrl}?page=${page}`

@@ -0,0 +25,4 @@
+      const url = `${baseUrl}?page=${page}`
+      const res = await fetch(url, { headers: this.headers })
+
+      if (!res.ok) {

@@ -0,0 +28,4 @@
+      if (!res.ok) {
+        throw new Error(`GET ${url} failed: HTTP ${res.status}`)
+      }
+

@@ -0,0 +14,4 @@
+ *
+ * @returns {Promise<void>} 流程完成時 resolve;設定驗證或讀取 API 失敗時 reject。
+ */
+async function main() {

@@ -0,0 +23,4 @@
+
+  separator()
+}
+

@@ -0,0 +11,4 @@
+ * @param {number} keepCount 要保留的筆數
+ * @returns {any[]} 需要刪除的成品(較舊者)
+ */
+export function selectReleasesToDelete(releases, keepCount) {

@@ -0,0 +18,4 @@
+  return sorted.slice(keepCount)
+}
+
+/**

@@ -0,0 +40,4 @@
+  const toDelete = selectReleasesToDelete(releases, config.keepCount)
+
+  for (const release of toDelete) {
+    const { id, tag_name: tag, name } = release

@@ -0,0 +43,4 @@
+    const { id, tag_name: tag, name } = release
+
+    if (isEmptyOrNull(id)) {
+      warn(`略過沒有 id 的成品: ${tag} (${name})`)

@@ -0,0 +32,4 @@
+ * @param {ReturnType<import('./config.js').loadConfig>} config
+ */
+export async function cleanupOrphanTags(client, config) {
+  section('刪除未指定 release 的 tag')

@@ -0,0 +43,4 @@
+  info(`TAG_COUNT=${tags.length}`)
+
+  for (const { tag, action } of categorizeTags(tags, releaseTagNames)) {
+    if (action === 'skip') {

@@ -0,0 +53,4 @@
+      continue
+    }
+
+    const url = `${config.tagApiUrl}/${tag.name}`

@@ -0,0 +33,4 @@
+
+  info(`GITEA_SERVER_URL=${serverUrl}`)
+  requireValue('GITEA_SERVER_URL', serverUrl)
+  requireUrl('GITEA_SERVER_URL', serverUrl)

@@ -0,0 +30,4 @@
+   * @param {string} baseUrl 不含 query string 的 API 位址(本方法會自行附加 `?page=N`)
+   * @returns {Promise<any[]>} 所有頁面合併後的項目陣列;無資料時為空陣列
+   * @throws {Error} 任一頁回應 HTTP 非 2xx(`!res.ok`)時拋出,訊息含 URL 與狀態碼
+   */

@@ -0,0 +45,4 @@
+      if (!res.ok) {
+        const body = await res.text().catch(() => '')
+        throw new Error(
+          `GET ${url} failed: HTTP ${res.status}${body ? ` - ${body.slice(0, 200)}` : ''}`,

@@ -0,0 +51,4 @@
+
+      // 確認回應確實是 JSON,避免 API 回傳 HTML 錯誤頁時 res.json() 拋出難以理解的 SyntaxError。
+      const contentType = res.headers.get('content-type') || ''
+      if (!contentType.includes('application/json')) {

@@ -0,0 +52,4 @@
+      // 確認回應確實是 JSON,避免 API 回傳 HTML 錯誤頁時 res.json() 拋出難以理解的 SyntaxError。
+      const contentType = res.headers.get('content-type') || ''
+      if (!contentType.includes('application/json')) {
+        const body = await res.text().catch(() => '')

@@ -0,0 +56,4 @@
+        throw new Error(
+          `GET ${url} returned non-JSON content-type "${contentType}": ${body.slice(0, 200)}`,
+        )
+      }

@@ -0,0 +64,4 @@
+      }
+
+      all.push(...items)
+      page += 1

@@ -0,0 +31,4 @@
+ */
+function reportFatal(error) {
+  if (error instanceof Error) {
+    fail(`${error.name}: ${error.message}`)

@@ -0,0 +43,4 @@
+// 僅在直接以 `node index.js` 執行時啟動主流程;被測試 import 時不自動執行,方便撰寫整合測試。
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    reportFatal(error)

@@ -0,0 +34,4 @@
+ */
+export async function cleanupReleases(client, config) {
+  section('取得成品資訊')
+  info(`GET ${config.releaseApiUrl}`)

@@ -0,0 +40,4 @@
+  info(`RELEASE_COUNT=${releases.length}`)
+  info(`KEEP_COUNT=${config.keepCount}`)
+
+  if (releases.length <= config.keepCount) {

@@ -0,0 +43,4 @@
+  section('刪除未指定 release 的 tag')
+
+  // 重新取得 release 清單,得到刪除舊版本後仍指定 tag 的成品
+  const currentReleases = await client.fetchAllPages(config.releaseApiUrl)

@@ -0,0 +44,4 @@
+ */
+export function requireUrl(name, value) {
+  let url
+  try {

@@ -0,0 +56,4 @@
+      })
+
+      if (!res.ok) {
+        const body = sanitizeBody(await res.text().catch(() => ''))

@@ -0,0 +56,4 @@
+      })
+
+      if (!res.ok) {
+        const body = sanitizeBody(await res.text().catch(() => ''))

@@ -0,0 +35,4 @@
+export async function cleanupReleases(client, config) {
+  section('取得成品資訊')
+  info(`GET ${config.releaseApiUrl}`)
+

@@ -0,0 +33,4 @@
+
+  info(`GITEA_SERVER_URL=${serverUrl}`)
+  requireValue('GITEA_SERVER_URL', serverUrl)
+  requireUrl('GITEA_SERVER_URL', serverUrl)

@@ -0,0 +30,4 @@
+    this.headers = {}
+    if (token) {
+      this.headers.Authorization = `token ${token}`
+    }

@@ -0,0 +2,4 @@
+
+const LINE = '=================================================='
+const SUBLINE = '--------------------------------------------------'
+

@@ -0,0 +34,4 @@
+ */
+export async function cleanupReleases(client, config) {
+  section('取得成品資訊')
+  info(`GET ${config.releaseApiUrl}`)

@@ -0,0 +40,4 @@
+  info(`RELEASE_COUNT=${releases.length}`)
+  info(`KEEP_COUNT=${config.keepCount}`)
+
+  if (releases.length <= config.keepCount) {

@@ -0,0 +43,4 @@
+  if (releases.length <= config.keepCount) {
+    success('沒有需要清理的舊版本成品')
+    return
+  }

@@ -0,0 +53,4 @@
+
+    if (isEmptyOrNull(id)) {
+      warn(`略過沒有 id 的成品: ${tag} (${name})`)
+      continue

@@ -0,0 +30,4 @@
+    this.headers = {}
+    if (token) {
+      this.headers.Authorization = `token ${token}`
+    }

@@ -0,0 +44,4 @@
+ * 要求值為合法的 http/https URL,藉此避免設定來源指向格式錯誤或非預期協定的伺服器(降低 SSRF 風險)。
+ * @param {string} name 欄位名稱,用於組出錯誤訊息
+ * @param {string} value 待檢查的 URL 字串
+ * @throws {Error} 當 value 無法解析為 URL 時丟出 `${name} must be a valid URL`;

@@ -0,0 +30,4 @@
+  const repository = env.GITEA_REPOSITORY
+  const keepCountRaw = env.KEEP_COUNT
+  const token = env.GITEA_TOKEN
+

@@ -0,0 +10,4 @@
+/**
+ * 將回應內容整理成可安全寫入錯誤訊息的片段:移除控制字元(避免換行等造成的 log 注入)並限制長度。
+ * @param {string} text 原始回應文字
+ * @returns {string} 清理後、最長 200 字元的片段

@@ -0,0 +60,4 @@
+      const res = await fetch(url, {
+        headers: this.headers,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      })

@@ -0,0 +63,4 @@
+      })
+
+      if (!res.ok) {
+        const body = sanitizeBody(await res.text().catch(() => ''))

@@ -0,0 +74,4 @@
+      if (!contentType.includes('application/json')) {
+        const body = sanitizeBody(await res.text().catch(() => ''))
+        throw new Error(
+          `GET ${url} returned non-JSON content-type "${contentType}"${body ? `: ${body}` : ''}`,

@@ -0,0 +98,4 @@
+      for (const item of items) {
+        all.push(item)
+      }
+      page += 1

@@ -0,0 +28,4 @@
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    failError(error)
+    process.exit(1)

@@ -0,0 +6,4 @@
+/**
+ * 在前後換行的情況下輸出一條等號分隔線至 stdout,用於視覺上區隔不同階段的輸出。
+ */
+export function separator() {

@@ -0,0 +14,4 @@
+export function selectReleasesToDelete(releases, keepCount) {
+  // 解析 created_at;格式無效或缺漏時視為最舊(0),避免 NaN 造成排序結果不可預期。
+  const createdTime = (release) => {
+    const time = Date.parse(release?.created_at)

@@ -0,0 +34,4 @@
+ */
+export async function cleanupReleases(client, config) {
+  section('取得成品資訊')
+  info(`GET ${config.releaseApiUrl}`)

@@ -0,0 +43,4 @@
+  if (releases.length <= config.keepCount) {
+    success('沒有需要清理的舊版本成品')
+    return
+  }

@@ -0,0 +18,4 @@
+  const keep = new Set(releaseTagNames)
+
+  return tags.map((tag) => {
+    if (isEmptyOrNull(tag.name)) {

@@ -0,0 +43,4 @@
+  section('刪除未指定 release 的 tag')
+
+  // 重新取得 release 清單,得到刪除舊版本後仍指定 tag 的成品
+  const currentReleases = await client.fetchAllPages(config.releaseApiUrl)

@@ -0,0 +11,4 @@
+ * @param {*} value 待判斷的值
+ * @returns {boolean} 當值為 `undefined`、`null`、空字串或字串 `"null"` 時回傳 true
+ */
+export function isEmptyOrNull(value) {

@@ -0,0 +22,4 @@
+/**
+ * 與 Gitea REST API 溝通的輕量 HTTP 客戶端,負責帶上認證標頭、分頁讀取清單與發出刪除請求。
+ * 取代原 bash 版本以 `curl`/`jq` 進行的 API 操作。
+ */

@@ -0,0 +20,4 @@
+  // 先一次性計算每筆的時間戳,避免在排序比較中重複呼叫 Date.parse。
+  return releases
+    .map((release) => ({ release, time: createdTime(release) }))
+    .sort((a, b) => b.time - a.time)

@@ -0,0 +25,4 @@
+    .slice(keepCount)
+}
+
+/**

@@ -0,0 +45,4 @@
+  info(`KEEP_COUNT=${config.keepCount}`)
+
+  if (releases.length <= config.keepCount) {
+    success('沒有需要清理的舊版本成品')

@@ -0,0 +56,4 @@
+    const { id, tag_name: tag, name } = release
+
+    if (isEmptyOrNull(id)) {
+      warn(`略過沒有 id 的成品: ${tag} (${name})`)

@@ -0,0 +62,4 @@
+    }
+
+    // 對 tag 名稱做編碼,避免名稱中的特殊字元被拼接進 URL(防路徑穿越);一般 tag 名編碼後不變。
+    const url = `${config.tagApiUrl}/${encodeURIComponent(tag.name)}`

@@ -0,0 +67,4 @@
+
+    const code = await client.deleteResource(url)
+    if (code === 204) {
+      success(`成功刪除未指定 release 的 tag: ${tag.name}`)

@@ -0,0 +60,4 @@
+test('loadConfig 在 GITEA_TOKEN 為空字串時視為匿名(token 為 null)', () => {
+  const cfg = loadConfig({ ...base, GITEA_TOKEN: '' })
+  assert.equal(cfg.token, null)
+})

@@ -0,0 +30,4 @@
+})
+
+test('fetchAllPages 逐頁讀取直到空陣列', async () => {
+  const pages = {

@@ -0,0 +74,4 @@
+test('cleanupReleases 在未超過保留數時不刪除', async () => {
+  const client = fakeClient([
+    { id: 1, tag_name: 'v1', name: 'n1', created_at: '2024-01-01T00:00:00Z' },
+  ])

@@ -0,0 +70,4 @@
+})
+
+test('cleanupOrphanTags 在所有 tag 都被指定時不刪除', async () => {
+  const client = fakeClient({

@@ -0,0 +17,4 @@
+
+test('isEmptyOrNull 對有效值回傳 false', () => {
+  assert.equal(isEmptyOrNull('value'), false)
+  assert.equal(isEmptyOrNull('0'), false)

@@ -0,0 +31,4 @@
+  const keepCountRaw = env.KEEP_COUNT
+  const token = env.GITEA_TOKEN
+
+  info(`GITEA_SERVER_URL=${serverUrl}`)

@@ -0,0 +32,4 @@
+  const token = env.GITEA_TOKEN
+
+  info(`GITEA_SERVER_URL=${serverUrl}`)
+  requireValue('GITEA_SERVER_URL', serverUrl)

@@ -0,0 +7,4 @@
+// 分頁讀取的最大頁數上限,作為安全斷點:即使 API 異常未以空陣列結尾,也不致無限迴圈耗盡資源。
+const MAX_PAGES = 1000
+
+/**

@@ -0,0 +103,4 @@
+
+    return all
+  }
+

@@ -0,0 +43,4 @@
+export function warn(message) {
+  process.stdout.write(`[WARN] ${message}\n`)
+}
+

@@ -0,0 +50,4 @@
+ */
+export function fail(message) {
+  process.stderr.write(`[ERR]  ${message}\n`)
+}

@@ -0,0 +17,4 @@
+    const time = Date.parse(release?.created_at)
+    return Number.isNaN(time) ? 0 : time
+  }
+  // 先一次性計算每筆的時間戳,避免在排序比較中重複呼叫 Date.parse。

@@ -0,0 +20,4 @@
+  // 先一次性計算每筆的時間戳,避免在排序比較中重複呼叫 Date.parse。
+  return releases
+    .map((release) => ({ release, time: createdTime(release) }))
+    .sort((a, b) => b.time - a.time)

@@ -0,0 +25,4 @@
+    .slice(keepCount)
+}
+
+/**

@@ -0,0 +43,4 @@
+  const releases = await client.fetchAllPages(config.releaseApiUrl)
+  info(`RELEASE_COUNT=${releases.length}`)
+  info(`KEEP_COUNT=${config.keepCount}`)
+

@@ -0,0 +31,4 @@
+  const keepCountRaw = env.KEEP_COUNT
+  const token = env.GITEA_TOKEN
+
+  info(`GITEA_SERVER_URL=${serverUrl}`)

@@ -0,0 +60,4 @@
+      const res = await fetch(url, {
+        headers: this.headers,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      })

@@ -0,0 +103,4 @@
+
+    return all
+  }
+

@@ -0,0 +112,4 @@
+  async deleteResource(url) {
+    const res = await fetch(url, {
+      method: 'DELETE',
+      headers: this.headers,

@@ -0,0 +18,4 @@
+  const config = loadConfig()
+  const client = new GiteaClient({ token: config.token })
+
+  await cleanupReleases(client, config)

@@ -0,0 +43,4 @@
+ */
+export async function cleanupReleases(client, config) {
+  section('取得成品資訊')
+  info(`GET ${config.releaseApiUrl}`)

@@ -0,0 +61,4 @@
+    const { id, tag_name: tag, name } = release
+
+    if (isEmptyOrNull(id)) {
+      warn(`略過沒有 id 的成品: ${tag} (${name})`)

@@ -0,0 +16,4 @@
+ */
+export function categorizeTags(tags, releaseTagNames) {
+  const keep = new Set(releaseTagNames)
+

@@ -0,0 +43,4 @@
+  section('刪除未指定 release 的 tag')
+
+  // 重新取得 release 清單,得到刪除舊版本後仍指定 tag 的成品
+  const currentReleases = await client.fetchAllPages(config.releaseApiUrl)

@@ -0,0 +59,4 @@
+    if (action === 'keep') {
+      info(`保留指定 release 的 tag: ${tag.name}`)
+      continue
+    }

@@ -0,0 +30,4 @@
+  const rawServerUrl = env.GITEA_SERVER_URL
+  const serverUrl =
+    typeof rawServerUrl === 'string' ? rawServerUrl.replace(/\/+$/, '') : rawServerUrl
+  const repository = env.GITEA_REPOSITORY

@@ -0,0 +60,4 @@
+    releaseApiUrl: `${serverUrl}/api/v1/repos/${repository}/releases`,
+    tagApiUrl: `${serverUrl}/api/v1/repos/${repository}/tags`,
+  }
+}

@@ -0,0 +112,4 @@
+  async deleteResource(url) {
+    const res = await fetch(url, {
+      method: 'DELETE',
+      headers: this.headers,

@@ -0,0 +42,4 @@
+ * @returns {Promise<void>}
+ */
+export async function cleanupReleases(client, config) {
+  section('取得成品資訊')

@@ -0,0 +43,4 @@
+ */
+export async function cleanupReleases(client, config) {
+  section('取得成品資訊')
+  info(`GET ${config.releaseApiUrl}`)

@@ -0,0 +53,4 @@
+  for (const { tag, action } of categorizeTags(tags, releaseTagNames)) {
+    if (action === 'skip') {
+      warn('略過沒有名稱的 tag')
+      continue

@@ -0,0 +44,4 @@
+export async function cleanupReleases(client, config) {
+  section('取得成品資訊')
+  info(`GET ${config.releaseApiUrl}`)
+

@@ -0,0 +49,4 @@
+  info(`GET ${config.tagApiUrl}`)
+  const tags = await client.fetchAllPages(config.tagApiUrl)
+  info(`TAG_COUNT=${tags.length}`)
+

@@ -0,0 +51,4 @@
+  info(`TAG_COUNT=${tags.length}`)
+
+  for (const { tag, action } of categorizeTags(tags, releaseTagNames)) {
+    if (action === 'skip') {