From fcf7680e49feb723a23ab2baef2c666a8eae8224 Mon Sep 17 00:00:00 2001 From: alex Date: Mon, 7 Sep 2026 21:14:23 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E8=87=AA=20fox=20monorepo=20=E7=A7=BB?= =?UTF-8?q?=E5=87=BA=E6=88=90=E7=8D=A8=E7=AB=8B=E5=85=AC=E9=96=8B=E5=80=89?= =?UTF-8?q?=E5=BA=AB=EF=BC=88fox=20#49=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 自 alterminal/fox 的 cli/ 目錄以 git subtree split 移出（保留 git 歷史）。 - package.json：改為獨立專案（移除 private、補 repository／homepage／files、 增加 packageManager pnpm@9.15.3）。 - README／docs/cli-install.md：路徑與指令改為本倉庫根目錄版型 （node dist/cli.js、pnpm build；獨立安裝不會建立 node_modules/.bin/fox， 掛 PATH 改用 symlink）。 - 新增 .gitignore 與 pnpm-lock.yaml。 - 驗證：pnpm install + pnpm build + node dist/cli.js --help（exit 0）、 未知命令 exit 2。 --- .gitignore | 24 +++++++ README.md | 14 +++-- docs/cli-install.md | 149 ++++++++++++++++++++++++++++++++++++++++++++ package.json | 16 ++++- pnpm-lock.yaml | 39 ++++++++++++ 5 files changed, 235 insertions(+), 7 deletions(-) create mode 100644 .gitignore create mode 100644 docs/cli-install.md create mode 100644 pnpm-lock.yaml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..342b359 --- /dev/null +++ b/.gitignore @@ -0,0 +1,24 @@ +# Node +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* +.pnpm-debug.log* +package-lock.json +yarn.lock + +# 建置輸出 +dist/ + +# 環境變數（勿提交真實憑證） +.env +.env.local +.env.*.local + +# 編輯器 / 系統 +.vscode/ +.idea/ +.DS_Store + +# 日誌 +*.log diff --git a/README.md b/README.md index 6cff63c..8f2c6fc 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Fox CLI — 與 Fox 後端互動的命令列工具 +> **本倉庫已從 `alterminal/fox` monorepo 的 `cli/` 目錄移出成獨立專案**（見 `alterminal/fox` issue #49），改為公開倉庫以開放安裝；git 歷史一併保留。 + > 專案狀態：M0–M3 已實作（M1：HTTP client、設定讀取、`tokens verify`／`auth status`；M2：`tokens create/list/revoke`、公開的 `novels get`；M3：`novels list/create/update`、`chapters …`、`generate …`）｜日期：2026-09-06 `fox` 是一個命令列工具，讓人與 **AI agent** 不經過前端，直接與 Fox 後端 API 互動：查詢／建立／編輯作品、管理 access token 等。目標是「一句命令拿到機器可解析的結果」，方便腳本、CI 與 agent 排程使用。 @@ -61,7 +63,7 @@ ## 五、技術棧與開發計畫 - **實作語言**：Node.js（≥22）＋ TypeScript，與 `frontend`／`backend` 同語言。 -- **加入 workspace**：實作開始時把 `cli` 加進根 `pnpm-workspace.yaml` 並建立 `package.json`（目前僅目錄與說明，先不動 workspace 設定）。 +- **獨立倉庫**：本專案位於 `alterminal/fox-cli`（自 `alterminal/fox` 移出，issue #49），不屬於 fox monorepo workspace；以 pnpm 於本倉庫根目錄安裝與建置。 里程碑： @@ -72,12 +74,14 @@ ## 開發 -> 使用者安裝與設定說明見 [docs/cli-install.md](../docs/cli-install.md)。 +> 使用者安裝與設定說明見 [docs/cli-install.md](./docs/cli-install.md)。 ```bash -pnpm install # 倉庫根目錄 -pnpm --filter fox-cli build -pnpm --filter fox-cli start <子命令> # 例如 auth status；不要加 "--"（pnpm 9 會把它當參數） +git clone https://gitea.alterminal.com/alterminal/fox-cli.git +cd fox-cli +pnpm install +pnpm build +node dist/cli.js <子命令> # 例如 auth status ``` 結構：`src/cli.ts`（進入點與分發）、`src/command.ts`（參數解析與註冊表）、 diff --git a/docs/cli-install.md b/docs/cli-install.md new file mode 100644 index 0000000..90457f5 --- /dev/null +++ b/docs/cli-install.md @@ -0,0 +1,149 @@ +# Fox CLI 安裝指南 + +> 適用對象：想在命令列使用 `fox` 與 Fox 後端互動的人與 AI agent。 +> 命令功能、設計原則與開發計畫見 [README.md](../README.md)。 +> 本指南以 macOS／Linux 為主（Windows 差異處另行註記）。 + +## 一、前置需求 + +| 項目 | 需求 | 說明 | +|------|------|------| +| Node.js | ≥ 22 | CLI 使用內建 `fetch`，**零執行期相依**（無第三方套件） | +| pnpm | 任意近期版本 | 僅安裝與建置階段需要 | +| git | 任意近期版本 | 取得原始碼 | +| Fox 後端 | 可連線的 API 位址 | 見第四節；本機開發預設 `http://localhost:3000` | + +檢查版本： + +```bash +node --version # 應為 v22 以上 +pnpm --version +``` + +沒有 pnpm 時可用 Corepack（Node 內建）或 npm 安裝： + +```bash +corepack enable # 或 +npm install -g pnpm +``` + +> CLI 是純客戶端工具：**不需要** Postgres／MinIO（`docker compose`）或前端，只要網路上連得到後端 API 即可。 + +## 二、取得與建置 + +```bash +git clone https://gitea.alterminal.com/alterminal/fox-cli.git +cd fox-cli +pnpm install # 安裝相依（typescript／@types/node，僅建置需要） +pnpm build # 以 tsc 編譯到 dist/ +``` + +建置產物 `dist/` 是純 JavaScript，只使用 Node 內建模組，可整個目錄複製到其他有 Node ≥22 的機器直接執行。 + +## 三、執行方式（擇一） + +**1. 倉庫內直接使用** + +```bash +node dist/cli.js --help +# 或 +pnpm start auth status +``` + +注意：`pnpm start -- <子命令>` 這種含 `--` 的寫法，在 pnpm 9 會把 `--` 當成參數傳給程式而報「未知命令」——**不要加 `--`**。 + +**2. 掛上 PATH（推薦）** + +```bash +mkdir -p ~/.local/bin +ln -s "$(pwd)/dist/cli.js" ~/.local/bin/fox +# 確認 ~/.local/bin 在 PATH 內（echo $PATH）；沒有就加進 shell 設定檔後重開 shell +fox --help +``` + +> symlink 指向倉庫內的 `dist/cli.js`；`pnpm build` 之後即是新版（pnpm 不會為倉庫本體建立 bin 連結，掛 PATH 請用 symlink）。 + +**3. 不建連結，直接以 node 執行** + +```bash +node dist/cli.js --help +``` + +## 四、設定：API 位址與 access token + +讀取優先順序（高 → 低）： + +1. `--api-url`／`--token` 參數 +2. 環境變數 `FOX_API_URL`／`FOX_API_TOKEN` +3. 設定檔 `~/.config/fox/cli.json` +4. `apiUrl` 預設 `http://localhost:3000`（token 無預設） + +**環境變數（推薦，適合 agent／CI）** + +```bash +export FOX_API_URL="https://api.fox.example.com" +export FOX_API_TOKEN="fpat_…" # token 值請見下方安全說明 +``` + +**設定檔** + +```bash +mkdir -p ~/.config/fox +umask 077 +cat > ~/.config/fox/cli.json <<'EOF' +{ + "apiUrl": "https://api.fox.example.com", + "token": "fpat_…" +} +EOF +chmod 600 ~/.config/fox/cli.json +``` + +Windows 的對應路徑為 `%USERPROFILE%\.config\fox\cli.json`。 + +> `--token ` 會留在 shell 歷史與 process list，僅供本機快速測試，不建議日常使用。 + +**取得 access token**：在 Fox 網頁端以自己的帳號建立，或由管理員通過 `POST /access-tokens` 建立。token 以 `fpat_` 開頭，**原始值只在建立當下顯示一次**。之後隨時可用 `fox tokens verify` 確認有效性（過期或撤銷會回 401）。 + +**安全原則**：token 只存放在環境變數或本機設定檔（權限 600），**絕不寫進 commit、issue、PR 或任何儲存庫內容**。經公開渠道交付時須以收受方公開金鑰加密（組織慣例見 `alterminal/agents` 的 AGENTS.md 2.3）。 + +## 五、驗證安裝 + +```bash +fox --help # 印出命令清單（exit 0） +fox auth status # 公開端點：查後端登入／SSO 設定 +fox tokens verify # 需要 token：有效回 exit 0；缺少或無效回 exit 1 並在 stderr 說明 +``` + +| exit code | 意義 | +|-----------|------| +| 0 | 成功 | +| 1 | 執行失敗（後端 4xx/5xx、網路錯誤、缺 token） | +| 2 | 用法錯誤（缺參數、未知命令） | + +stdout 只輸出**單一 JSON**（可直接管給 `jq`），人類可讀訊息一律走 stderr： + +```bash +fox novels get my-novel | jq '.title' +``` + +## 六、更新與解除安裝 + +```bash +# 更新 +cd fox-cli +git pull +pnpm install && pnpm build + +# 解除安裝 +rm ~/.local/bin/fox # 若有建連結 +rm -rf /path/to/fox-cli # 倉庫本體 +rm ~/.config/fox/cli.json # 內含 token，一併刪除 +``` + +## 疑難排解 + +- **`fox: command not found`**：`~/.local/bin` 不在 PATH，或還沒建 symlink（見第三節）。 +- **`未知命令：fox --…`**：用了 `pnpm start -- <子命令>` 的寫法；把 `--` 拿掉（見第三節）。 +- **`無法連線到 http://localhost:3000`**：後端沒開或位址不對；設定 `FOX_API_URL` 指向正確的 API 位址。 +- **`缺少 access token`**：需要授權的命令（如 `tokens verify`）沒有設定 token；見第四節。 diff --git a/package.json b/package.json index 3481bb9..015e97c 100644 --- a/package.json +++ b/package.json @@ -1,12 +1,23 @@ { "name": "fox-cli", "version": "0.1.0", - "private": true, "description": "Fox（狐）命令列工具：直接與 Fox 後端 API 互動（供人與 AI agent 使用）", "type": "module", "bin": { "fox": "./dist/cli.js" }, + "files": [ + "dist", + "README.md" + ], + "repository": { + "type": "git", + "url": "https://gitea.alterminal.com/alterminal/fox-cli.git" + }, + "homepage": "https://gitea.alterminal.com/alterminal/fox-cli", + "bugs": { + "url": "https://gitea.alterminal.com/alterminal/fox-cli/issues" + }, "engines": { "node": ">=22" }, @@ -18,5 +29,6 @@ "devDependencies": { "@types/node": "^22.10.0", "typescript": "^5.7.0" - } + }, + "packageManager": "pnpm@9.15.3" } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml new file mode 100644 index 0000000..b6289c3 --- /dev/null +++ b/pnpm-lock.yaml @@ -0,0 +1,39 @@ +lockfileVersion: '9.0' + +settings: + autoInstallPeers: true + excludeLinksFromLockfile: false + +importers: + + .: + devDependencies: + '@types/node': + specifier: ^22.10.0 + version: 22.20.1 + typescript: + specifier: ^5.7.0 + version: 5.9.3 + +packages: + + '@types/node@22.20.1': + resolution: {integrity: sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q==} + + typescript@5.9.3: + resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==} + engines: {node: '>=14.17'} + hasBin: true + + undici-types@6.21.0: + resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==} + +snapshots: + + '@types/node@22.20.1': + dependencies: + undici-types: 6.21.0 + + typescript@5.9.3: {} + + undici-types@6.21.0: {}