規劃 App 管理指令介面規格(bear apps CRUD) #5

Closed
opened 2026-09-07 22:30:47 +08:00 by alex · 1 comment
Member

拆自 #4(實現App管理指令)。

背景

bear-cli 的 docs/commands.md 目前只規劃了登入/身分類指令,bear apps 標為 P3 暫緩且只列清單。要「管理」App(建立/更新/輪轉 secret/啟停用),需要先把指令介面規格定下來。伺服器端 API 另由 alterminal/bear#28 提供。

範圍

更新 docs/commands.md(必要時同步 README),規劃 App 管理指令群,至少涵蓋:

  1. bear apps list [--visibility public|internal] [--status active|inactive] [--json]
  2. bear apps show <client-id>
  3. bear apps create(client_id、url、title、method、visibility、redirect URLs、scopes、sub 等;PKCE 需綁 jwk)
  4. bear apps update <client-id>
  5. bear apps rotate-secret <client-id>(一次性顯示新 secret,提示保存)
  6. bear apps toggle <client-id>
  7. 認證一律用既有 PAT 憑證(bear login --token);admin 限定操作的錯誤呈現(403)。
  8. 退出碼沿用第 4 節總表,另補管理類錯誤(如 403 對應碼)。
  9. --json 輸出格式。

驗收

  • 規格文件更新並開 PR(審核者建議 chenyunda218 或 queena)。
  • 指令、選項、行為、輸出、退出碼、錯誤處理皆有定義,可作為實作依據。
  • 註明依賴 alterminal/bear#28 的 API 端點。
拆自 #4(實現App管理指令)。 ## 背景 bear-cli 的 `docs/commands.md` 目前只規劃了登入/身分類指令,`bear apps` 標為 P3 暫緩且只列清單。要「管理」App(建立/更新/輪轉 secret/啟停用),需要先把指令介面規格定下來。伺服器端 API 另由 alterminal/bear#28 提供。 ## 範圍 更新 `docs/commands.md`(必要時同步 README),規劃 App 管理指令群,至少涵蓋: 1. `bear apps list [--visibility public|internal] [--status active|inactive] [--json]` 2. `bear apps show <client-id>` 3. `bear apps create`(client_id、url、title、method、visibility、redirect URLs、scopes、sub 等;PKCE 需綁 jwk) 4. `bear apps update <client-id>` 5. `bear apps rotate-secret <client-id>`(一次性顯示新 secret,提示保存) 6. `bear apps toggle <client-id>` 7. 認證一律用既有 PAT 憑證(`bear login --token`);admin 限定操作的錯誤呈現(403)。 8. 退出碼沿用第 4 節總表,另補管理類錯誤(如 403 對應碼)。 9. `--json` 輸出格式。 ## 驗收 - 規格文件更新並開 PR(審核者建議 chenyunda218 或 queena)。 - 指令、選項、行為、輸出、退出碼、錯誤處理皆有定義,可作為實作依據。 - 註明依賴 alterminal/bear#28 的 API 端點。
ceo was assigned by alex 2026-09-07 22:30:47 +08:00
Member

已完成規格規劃,開了 PR #7(審核者 chenyunda218):

  • docs/commands.md 3.6 由「P3 暫緩清單」擴充為完整 bear apps 指令群規格:list/show/create/update/rotate-secret/toggle,含選項表、行為、人類可讀與 --json 輸出範例、退出碼。
  • 認證:一律 PAT Bearer;401 → 退出碼 3(重新登入);403 非 admin → 新增退出碼 8,明確提示需 admin 權限且不重試。
  • Secret 處理:client_secret 僅 create/rotate-secret 成功當下一次性顯示,不寫入憑證檔/log/版本庫;其餘指令回應永不含 secret。
  • 第 4 節總表補退出碼 8;第 7 節開放問題改寫(公開清單是否開放非 admin)並新增「API 路徑參數 UUID vs client_id」待 bear#28 定案;第 8 節對應關係列出全部六個端點並註明依賴 alterminal/bear#28。
  • README 指令總覽與 P3 里程碑同步更新。

欄位語意已對照 bear 倉庫 Bear.App changeset 驗證(method:client_secret/PKCE;visibility:public/internal;PKCE 必綁 jwk_id)。實作待 bear#28 API 落地後進行,issue 保持開啟。

已完成規格規劃,開了 PR #7(審核者 chenyunda218): - **docs/commands.md 3.6** 由「P3 暫緩清單」擴充為完整 `bear apps` 指令群規格:`list`/`show`/`create`/`update`/`rotate-secret`/`toggle`,含選項表、行為、人類可讀與 `--json` 輸出範例、退出碼。 - **認證**:一律 PAT Bearer;401 → 退出碼 `3`(重新登入);403 非 admin → 新增退出碼 `8`,明確提示需 admin 權限且不重試。 - **Secret 處理**:`client_secret` 僅 `create`/`rotate-secret` 成功當下一次性顯示,不寫入憑證檔/log/版本庫;其餘指令回應永不含 secret。 - **第 4 節**總表補退出碼 `8`;**第 7 節**開放問題改寫(公開清單是否開放非 admin)並新增「API 路徑參數 UUID vs client_id」待 bear#28 定案;**第 8 節**對應關係列出全部六個端點並註明依賴 alterminal/bear#28。 - **README** 指令總覽與 P3 里程碑同步更新。 欄位語意已對照 bear 倉庫 `Bear.App` changeset 驗證(method:`client_secret`/`PKCE`;visibility:`public`/`internal`;PKCE 必綁 `jwk_id`)。實作待 bear#28 API 落地後進行,issue 保持開啟。
Sign in to join this conversation.
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: alterminal/bear-cli#5