chore: 自 fox monorepo 移出成獨立公開倉庫（fox #49）
- 自 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。
This commit is contained in:
+24
@@ -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
|
||||||
@@ -1,5 +1,7 @@
|
|||||||
# Fox CLI — 與 Fox 後端互動的命令列工具
|
# 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
|
> 專案狀態：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 排程使用。
|
`fox` 是一個命令列工具，讓人與 **AI agent** 不經過前端，直接與 Fox 後端 API 互動：查詢／建立／編輯作品、管理 access token 等。目標是「一句命令拿到機器可解析的結果」，方便腳本、CI 與 agent 排程使用。
|
||||||
@@ -61,7 +63,7 @@
|
|||||||
## 五、技術棧與開發計畫
|
## 五、技術棧與開發計畫
|
||||||
|
|
||||||
- **實作語言**：Node.js（≥22）＋ TypeScript，與 `frontend`／`backend` 同語言。
|
- **實作語言**：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
|
```bash
|
||||||
pnpm install # 倉庫根目錄
|
git clone https://gitea.alterminal.com/alterminal/fox-cli.git
|
||||||
pnpm --filter fox-cli build
|
cd fox-cli
|
||||||
pnpm --filter fox-cli start <子命令> # 例如 auth status；不要加 "--"（pnpm 9 會把它當參數）
|
pnpm install
|
||||||
|
pnpm build
|
||||||
|
node dist/cli.js <子命令> # 例如 auth status
|
||||||
```
|
```
|
||||||
|
|
||||||
結構：`src/cli.ts`（進入點與分發）、`src/command.ts`（參數解析與註冊表）、
|
結構：`src/cli.ts`（進入點與分發）、`src/command.ts`（參數解析與註冊表）、
|
||||||
|
|||||||
@@ -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 <value>` 會留在 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；見第四節。
|
||||||
+14
-2
@@ -1,12 +1,23 @@
|
|||||||
{
|
{
|
||||||
"name": "fox-cli",
|
"name": "fox-cli",
|
||||||
"version": "0.1.0",
|
"version": "0.1.0",
|
||||||
"private": true,
|
|
||||||
"description": "Fox（狐）命令列工具：直接與 Fox 後端 API 互動（供人與 AI agent 使用）",
|
"description": "Fox（狐）命令列工具：直接與 Fox 後端 API 互動（供人與 AI agent 使用）",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"bin": {
|
"bin": {
|
||||||
"fox": "./dist/cli.js"
|
"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": {
|
"engines": {
|
||||||
"node": ">=22"
|
"node": ">=22"
|
||||||
},
|
},
|
||||||
@@ -18,5 +29,6 @@
|
|||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@types/node": "^22.10.0",
|
"@types/node": "^22.10.0",
|
||||||
"typescript": "^5.7.0"
|
"typescript": "^5.7.0"
|
||||||
}
|
},
|
||||||
|
"packageManager": "pnpm@9.15.3"
|
||||||
}
|
}
|
||||||
|
|||||||
Generated
+39
@@ -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: {}
|
||||||
Reference in New Issue
Block a user