fox-cli/README.md

Fox CLI — 與 Fox 後端互動的命令列工具

專案狀態：M0–M2 已實作（M1：HTTP client、設定讀取、tokens verify／auth status；M2：tokens create/list/revoke、公開的 novels get）｜日期：2026-09-04

fox 是一個命令列工具，讓人與 AI agent 不經過前端，直接與 Fox 後端 API 互動：查詢／建立／編輯作品、管理 access token 等。目標是「一句命令拿到機器可解析的結果」，方便腳本、CI 與 agent 排程使用。

一、設計原則

1. 非互動優先：所有命令不跳 prompt，參數與環境變數給齊即可執行。缺少必要參數直接報錯（非零 exit code），適合 AI agent 與 cron。
2. 機器可讀輸出：資料命令預設輸出 JSON（stdout 僅印 JSON，其餘訊息一律走 stderr）；人用格式之後再以 --pretty 提供。
3. 穩定的 exit code：0 成功；1 執行失敗（後端 4xx/5xx、網路錯誤）；用法錯誤（缺參數、未知子命令）同樣回非零，訊息在 stderr。
4. 冪等意識：文件會標明各命令是否幂等（如 tokens revoke 冪等、novels create 會因 slug 重複而失敗），供 agent 重試決策。
5. Secret 不落檔：token 只從環境變數或本機設定檔讀取（見下），絕不寫進 commit／issue／PR。

二、授權（access token）

後端的 access token（fpat_ 前綴）是 CLI 的主要憑證：

• 建立：先在 Fox 網頁端以帳號建立，或由管理員以 POST /access-tokens 建立；原始值只在建立時顯示一次。
• 讀取優先順序：
  1. 環境變數 FOX_API_TOKEN（推薦，適合 agent／CI）
  2. --token <value> 參數（注意：會留在 shell 歷史，僅供本機快速測試）
  3. 本機設定檔 ~/.config/fox/cli.json（{"apiUrl": "...", "token": "..."}，權限應設 600）
• 使用方式：每個請求帶 Authorization: Bearer <token>；先用 fox tokens verify 確認有效（過期／撤銷會回 401）。

後端 API 位址由 FOX_API_URL（或設定檔 apiUrl）指定，本機開發預設 http://localhost:3000。

三、命令規劃（對應後端端點）

命令	後端端點	說明
fox auth status	GET /auth/status	查詢登入／SSO 設定（公開）
fox tokens verify	GET /access-tokens/verify	驗證手中 token 是否有效
fox tokens create --name <名稱> [--expires-at <ISO8601>]	POST /access-tokens	建立新 token（回傳只出現一次的原始值）
fox tokens list	GET /access-tokens	列出 token（不含 hash／原始值）
fox tokens revoke <id>	DELETE /access-tokens/:id	撤銷 token（冪等）
fox novels get <slug>	GET /novels/:slug	查單一作品（公開）
fox novels list	GET /novels	列出自己的作品（需授權，見下）
fox novels create --title <書名> [--slug <slug>] [--synopsis <簡介>]	POST /novels	建立作品（需授權，見下）
fox novels update <slug> [--title ...] [--slug ...] [--synopsis ...]	PATCH /novels/:slug	更新作品（需授權，見下）

授權（issue #16 已補齊）：受保護端點（novels list/create/update、auth me）的 AuthGuard 現在同時接受 Authorization: Bearer <access token> 與瀏覽器 session（cookie）；Bearer 優先。access token 需綁定帳號（POST /access-tokens 帶 accountId，或由管理員建立時指定），未綁帳號的系統 token 只能用於 tokens verify。CLI 待 M3 補齊 novels list/create/update 命令。

四、AI agent 使用指引

• 每個命令都有 --help；未知命令回非零 exit code。
• 輸出為單一 JSON 物件，可直接 jq 解析；錯誤時 stderr 有人類可讀訊息，stdout 不印半成品。
• agent 拿到 token 的建議流程：由人透過加密渠道交付（組織公開金鑰加密，見 alterminal/agents 的 AGENTS.md 2.3），存入環境變數或設定檔，不寫入任何儲存庫內容。

五、技術棧與開發計畫

• 實作語言：Node.js（≥22）＋ TypeScript，與 frontend／backend 同語言。
• 加入 workspace：實作開始時把 cli 加進根 pnpm-workspace.yaml 並建立 package.json（目前僅目錄與說明，先不動 workspace 設定）。

里程碑：

• M0：子項目目錄＋README（完成）。
• M1：HTTP client、設定讀取、tokens verify／auth status（完成，見 src/http.ts、src/config.ts）。
• M2：tokens create/list/revoke、公開的 novels get（完成）。
• M3：novels list/create/update（視後端授權進度）、--pretty、錯誤處理打磨。

開發

使用者安裝與設定說明見 docs/cli-install.md。

pnpm install        # 倉庫根目錄
pnpm --filter fox-cli build
pnpm --filter fox-cli start <子命令>   # 例如 auth status；不要加 "--"（pnpm 9 會把它當參數）

結構：src/cli.ts（進入點與分發）、src/command.ts（參數解析與註冊表）、 src/config.ts（設定讀取）、src/http.ts（fetch 封裝）、src/commands.ts（各命令實作）、 src/errors.ts（錯誤與 exit code）。

exit code：0 成功；1 執行失敗（後端 4xx/5xx、網路錯誤）；2 用法錯誤。 tokens revoke 成功時輸出 {"ok": true, "id": <id>}（後端回 204 無內容）。

維護說明

1. 後端端點異動時，同步更新第三節對應表。
2. 命令列介面（參數、輸出欄位）保持向下相容；破壞性變更須在 README 註明版本。