@stellar_ai/mcp_fossil_scm 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/LICENSE +28 -0
  2. package/README.md +140 -113
  3. package/dist/capabilities.js +6 -7
  4. package/dist/cli.js +28 -24
  5. package/dist/config.js +7 -32
  6. package/dist/core/fossil.js +67 -79
  7. package/dist/core/gitignore.js +136 -0
  8. package/dist/core/sql.js +3 -2
  9. package/dist/index.js +8 -7
  10. package/dist/prompts.js +167 -0
  11. package/dist/server.js +6 -5
  12. package/dist/tools/admin.js +454 -86
  13. package/dist/tools/chat.js +22 -26
  14. package/dist/tools/common.js +14 -5
  15. package/dist/tools/forum.js +37 -29
  16. package/dist/tools/tickets.js +32 -11
  17. package/dist/tools/version-control.js +880 -105
  18. package/dist/tools/wiki.js +17 -18
  19. package/docs/README.md +31 -0
  20. package/docs/admin.md +663 -0
  21. package/docs/chat.md +152 -0
  22. package/docs/forum.md +146 -0
  23. package/docs/prompts.md +39 -0
  24. package/docs/tickets.md +179 -0
  25. package/docs/vcs.md +1089 -0
  26. package/docs/wiki.md +140 -0
  27. package/package.json +11 -6
  28. package/dist/capabilities.d.ts +0 -32
  29. package/dist/capabilities.js.map +0 -1
  30. package/dist/cli.d.ts +0 -27
  31. package/dist/cli.js.map +0 -1
  32. package/dist/config.d.ts +0 -27
  33. package/dist/config.js.map +0 -1
  34. package/dist/core/fossil.d.ts +0 -104
  35. package/dist/core/fossil.js.map +0 -1
  36. package/dist/core/sql.d.ts +0 -29
  37. package/dist/core/sql.js.map +0 -1
  38. package/dist/index.d.ts +0 -2
  39. package/dist/index.js.map +0 -1
  40. package/dist/server.d.ts +0 -13
  41. package/dist/server.js.map +0 -1
  42. package/dist/tools/admin.d.ts +0 -3
  43. package/dist/tools/admin.js.map +0 -1
  44. package/dist/tools/chat.d.ts +0 -10
  45. package/dist/tools/chat.js.map +0 -1
  46. package/dist/tools/common.d.ts +0 -9
  47. package/dist/tools/common.js.map +0 -1
  48. package/dist/tools/forum.d.ts +0 -3
  49. package/dist/tools/forum.js.map +0 -1
  50. package/dist/tools/tickets.d.ts +0 -8
  51. package/dist/tools/tickets.js.map +0 -1
  52. package/dist/tools/version-control.d.ts +0 -3
  53. package/dist/tools/version-control.js.map +0 -1
  54. package/dist/tools/wiki.d.ts +0 -3
  55. package/dist/tools/wiki.js.map +0 -1
package/docs/admin.md ADDED
@@ -0,0 +1,663 @@
1
+ # Admin 能力(`-c a`)說明
2
+
3
+ 本文件對應 `src/tools/admin.ts`(實現)與 `src/core/fossil.ts`(執行器),描述 `fossil-scm` 在
4
+ `-c a`(Admin)能力下暴露的 **11 個工具**、它們的確切行為、成功/失敗輸出形態,以及當前已知的邊界問題。
5
+
6
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後。
7
+
8
+ > 執行要求:Node.js >= 20。包內是編譯後的 `dist/**/*.js`(無 source map、無 `.d.ts`)。
9
+
10
+ ---
11
+
12
+ ## 1. 能力概覽
13
+
14
+ | 工具 | 作用 |
15
+ | --- | --- |
16
+ | `fossil_init` | 在**指定路徑**新建空倉庫資料庫 |
17
+ | `fossil_open` | 把指定倉庫開啟成 check-out |
18
+ | `fossil_close` | 關閉當前 check-out |
19
+ | `fossil_clone` | 克隆遠端/本地倉庫到目標 `.fossil` |
20
+ | `fossil_settings` | 讀 / 寫 Fossil 設定 |
21
+ | `fossil_remote` | 管理遠端倉庫 URL |
22
+ | `fossil_push` | 把本地可分享的變更送到遠端倉庫 |
23
+ | `fossil_pull` | 把遠端倉庫的可分享變更拉回本地 |
24
+ | `fossil_sync` | 與遠端倉庫雙向交換可分享的變更 |
25
+ | `fossil_rebuild` | 重建倉庫資料庫 |
26
+ | `fossil_config` | 匯出 / 匯入 / 合併 / 拉取 / 推送 / 重設設定區 |
27
+
28
+ `fossil_close`、`fossil_rebuild` 標記 destructive;`fossil_push`、`fossil_pull`、`fossil_sync`、`fossil_config` 標記 openWorld;`fossil_close`、`fossil_settings` 標記 idempotent。
29
+
30
+ 啟動方式:
31
+
32
+ ```bash
33
+ fossil-scm -c a --workspace /path/to/workspace
34
+ fossil-scm -c a --workspace /path/to/workspace --verbose
35
+ FOSSIL_WORKSPACE=/path/to/workspace fossil-scm -c a
36
+ ```
37
+
38
+ 此時握手返回的 `serverInfo.name` 為 `fossil-scm-a`,`serverInfo.version` 與 `package.json` 的版本一致
39
+ (冒煙測試會校驗)。Admin 組不包含任何 `v`/`f`/`t`/`w`/`c` 組的工具。
40
+
41
+ ---
42
+
43
+ ## 2. 通用約定
44
+
45
+ ### 2.1 `workspace`:唯一的目錄概念
46
+
47
+ 整個服務只用 **`workspace`** 這一個名字:工具參數、命令列參數、環境變數都用它。
48
+
49
+ | 層級 | 名稱 |
50
+ | --- | --- |
51
+ | 工具參數 | `workspace`(可選,字串) |
52
+ | 命令列參數 | `--workspace DIR` |
53
+ | 環境變數 | `FOSSIL_WORKSPACE` |
54
+ | 內部/結果欄位 | `outcome.workspace`,錯誤文本裡顯示為 `WORKSPACE: …` |
55
+
56
+ 解析順序(`resolveWorkspace`):
57
+
58
+ 1. 工具參數 `workspace`(相對路徑以**程序當前目錄**為基準 `path.resolve`)
59
+ 2. 否則 `--workspace` 指定的預設值
60
+ 3. 否則 `FOSSIL_WORKSPACE`
61
+ 4. 否則 **`process.cwd()`(工作目錄兜底)**
62
+
63
+ > `workspace` 既是 fossil 子程序的工作目錄,也是 `repository` 相對路徑的基準目錄。
64
+
65
+ ### 2.2 `repository`:倉庫位置沒有預設
66
+
67
+ `fossil_init`、`fossil_open` 的倉庫檔案位置**沒有任何預設值**(沒有 `.fossil_repositories` 目錄、不派生
68
+ 專案名檔名、不自作主張補 `.fossil` 後綴),必須由提示詞顯式給出:
69
+
70
+ | 參數 | 類型 | 必填/預設 | 說明 |
71
+ | --- | --- | --- | --- |
72
+ | `repository` | string | **必填** | 倉庫資料庫檔案路徑 |
73
+
74
+ 解析規則(`resolveRepoPath`):
75
+
76
+ | 傳入值 | 結果 |
77
+ | --- | --- |
78
+ | 絕對路徑 `/srv/repos/app.fossil` | 原樣使用(`path.normalize`) |
79
+ | 相對路徑 `repos/app.fossil` | `resolve(workspace, 'repos/app.fossil')` |
80
+ | 裸名 `app` | `resolve(workspace, 'app')` —— 路徑原樣使用,`.fossil` 後綴需自己寫 |
81
+ | 省略 | schema 校驗失敗(`repository` 為必填) |
82
+
83
+ - 目標檔案已存在 → 由 fossil 報錯(`file already exists: …`)。
84
+ - 父目錄不存在時工具會先 `mkdir -p`(`fossil_init`/`fossil_clone` 都會),見 §6.1。
85
+ - 其餘工具(`fossil_close`、`fossil_settings`)不接收倉庫路徑,它們作用於 `workspace` 裡已開啟的 check-out。
86
+
87
+ ### 2.3 命令執行與失敗語義
88
+
89
+ `runFossil`(`src/core/fossil.ts`)要點:
90
+
91
+ - `spawn(FOSSIL_BIN, args, { cwd: workspace })`,**不經過 shell**(參數原樣傳遞,無注入問題)。
92
+ - `FOSSIL_BIN` 預設 `fossil`,可用環境變數覆蓋。
93
+ - stdin **立即關閉**(需要互動回答時用 `input` 顯式喂資料),避免任何等待;
94
+ - 超時:預設 `FOSSIL_TIMEOUT_MS=30000`;`fossil_clone` 用 `FOSSIL_NETWORK_TIMEOUT_MS=600000`;
95
+ 超時先 `SIGTERM`,2 秒後 `SIGKILL`;
96
+ - 每條流最多緩衝 `FOSSIL_MAX_CAPTURE_BYTES=4194304` 位元組;
97
+ - 返回前按 `FOSSIL_MAX_OUTPUT_CHARS=120000` 截斷(保留前 60% + 後 40%,中間標註被截長度)。
98
+
99
+ 工具返回值統一為 MCP 文字結果:
100
+
101
+ - 成功:`isError` 未設定;`content[0].text` 為 stdout(去首尾空白),空輸出顯示 `(no output)`,
102
+ 部分工具附加一行說明(init/open/clone 的 note)。
103
+ - 失敗:`isError: true`,文字形如:
104
+
105
+ ```
106
+ ERROR: Fossil command failed (exit code 1).
107
+ <stderr 或 stdout>
108
+ STDOUT: / STDERR: (兩者都有時分別給出)
109
+ COMMAND: fossil init /tmp/ws2/repo2.fossil --project-name ws2
110
+ WORKSPACE: /tmp/ws2
111
+ ```
112
+
113
+ 超時 / 找不到可執行檔案 / workspace 不存在:
114
+
115
+ ```
116
+ ERROR: Fossil command timed out after 30s (partial output kept below).
117
+ ERROR: 'fossil' not found in PATH.
118
+ Install Fossil SCM and make sure it is on PATH, or set FOSSIL_BIN to the executable path.
119
+ ERROR: workspace directory '/tmp/missing' does not exist.
120
+ Point `workspace` (or --workspace) at a directory that exists and retry.
121
+ ```
122
+
123
+ 三種情形都帶 `COMMAND:` / `WORKSPACE:` 尾部。Node 對「可執行檔案不存在」和「子程序 cwd 不存在」都報 `ENOENT`,
124
+ 工具先看 workspace 是否為目錄,再決定給出哪條訊息。
125
+
126
+ ---
127
+
128
+ ## 3. 工具詳解
129
+
130
+ ### 3.1 `fossil_init`
131
+
132
+ 在給定路徑新建一個空倉庫資料庫。
133
+
134
+ | 參數 | 類型 | 必填/預設 | 說明 |
135
+ | --- | --- | --- | --- |
136
+ | `repository` | string | **必填** | 倉庫檔案路徑,見 §2.2 |
137
+ | `project_name` | string | workspace 目錄名(根目錄 `/` 時為 `project`) | 寫入倉庫的 `project-name` |
138
+ | `reveal_secrets` | boolean | `false` | 原樣返回 admin 初始密碼(預設脫敏為 `***`) |
139
+ | `workspace` | string | 見 §2.1 | 命令執行目錄 / 相對路徑基準 |
140
+
141
+ 執行:
142
+
143
+ ```bash
144
+ mkdir -p <dirname(repoPath)> # 工具先建父目錄
145
+ fossil init <repoPath> --project-name <finalProjectName> # cwd = workspace
146
+ ```
147
+
148
+ 成功(真實輸出,預設脫敏):
149
+
150
+ ```
151
+ project-name: ws2
152
+ project-id: 1e9aae87a94129d4bfc8b21f603f8bf189bd83c8
153
+ server-id: f26f5e8a2d3d2f0b341a496657706a7717258e7b
154
+ admin-user: stellar (initial password is "***")
155
+
156
+ Repository created at '/tmp/ws2/repo2.fossil' (project 'ws2').
157
+ ```
158
+
159
+ 傳 `reveal_secrets: true` 時該行顯示真實密碼:
160
+
161
+ ```
162
+ admin-user: stellar (initial password is "7XnEKoTitj")
163
+ ```
164
+
165
+ 參數校驗失敗(未給 `repository`,由 schema 攔截):
166
+
167
+ ```
168
+ Input validation error: Invalid arguments for tool fossil_init: repository: Invalid input: expected string, received undefined
169
+ ```
170
+
171
+ 失敗示例(檔案已存在):
172
+
173
+ ```
174
+ ERROR: Fossil command failed (exit code 1).
175
+ file already exists: /tmp/ws2/repo2.fossil
176
+ COMMAND: fossil init /tmp/ws2/repo2.fossil --project-name ws2
177
+ WORKSPACE: /tmp/ws2
178
+ ```
179
+
180
+ 注意:
181
+
182
+ - 建出來的只是資料庫;要工作區得再 `fossil_open`。
183
+ - 父目錄會被自動建立(`mkdir -p`),否則 `fossil init` 報 `SQLITE_CANTOPEN`。
184
+ - 輸出裡的 admin 初始密碼預設替換成 `***`;需要真實值時傳 `reveal_secrets: true`。
185
+
186
+ ### 3.2 `fossil_open`
187
+
188
+ 把指定倉庫開啟成 check-out。
189
+
190
+ | 參數 | 類型 | 必填/預設 | 說明 |
191
+ | --- | --- | --- | --- |
192
+ | `repository` | string | **必填** | 要開啟的倉庫檔案,見 §2.2 |
193
+ | `force` | boolean | `false` | `-f`:目錄非空時仍開啟 |
194
+ | `keep` | boolean | `false` | `-k`:保留磁碟上已有檔案不動 |
195
+ | `nested` | boolean | `false` | `--nested`:允許在外層 check-out 內部再開啟一個 check-out |
196
+ | `workdir` | string | workspace | `--workdir`;**相對路徑以 workspace 為基準**解析成絕對路徑 |
197
+ | `workspace` | string | 見 §2.1 | 命令執行目錄 |
198
+
199
+ 執行:
200
+
201
+ ```bash
202
+ fossil open <repoPath> [-f] [-k] [--nested] [--workdir <abs checkoutDir>] # cwd = workspace
203
+ ```
204
+
205
+ `checkoutDir` = `workdir ? resolve(workspace, workdir) : workspace`。
206
+
207
+ 成功:
208
+
209
+ ```
210
+ project-name: ws2
211
+ repository: /tmp/ws2/repo2.fossil
212
+ local-root: /dev/shm/tmp/ws2/
213
+ …
214
+ check-ins: 1
215
+
216
+ Opened repository '/tmp/ws2/repo2.fossil' in '/tmp/ws2'.
217
+ ```
218
+
219
+ check-out 目錄裡多出的是 fossil 自己的本地元資料(如 `.fslckout`)。
220
+
221
+ 失敗示例(目錄非空且未 `force`):
222
+
223
+ ```
224
+ ERROR: Fossil command failed (exit code 1).
225
+ directory /dev/shm/tmp/ws2 is not empty
226
+ use the -f (--force) option to override
227
+ or the -k (--keep) option to keep local files unchanged
228
+ COMMAND: fossil open /tmp/ws2/repo2.fossil
229
+ WORKSPACE: /tmp/ws2
230
+ ```
231
+
232
+ 注意:
233
+
234
+ - open 出來的 check-out 在 `checkoutDir`(`--workdir` 生效時與 `workspace` 不同),note 裡會明確給出該路徑。
235
+ - `workspace` 已經在外層 check-out 裡面時,fossil 報 `there is already an open tree at …`;
236
+ 要巢狀開啟就傳 `nested: true`,此時 `workspace` 指內層目錄。
237
+ - 設定不隨 open 變化:倉庫裡已有的配置原樣保留;想改設定用 `fossil_settings` 或專案裡的 `.fossil-settings/`。
238
+
239
+ ### 3.3 `fossil_close`
240
+
241
+ 關閉 check-out(保留倉庫資料庫,刪除本地 check-out 元資料)。
242
+
243
+ | 參數 | 類型 | 必填/預設 | 說明 |
244
+ | --- | --- | --- | --- |
245
+ | `force` | boolean | `false` | `-f`:忽略未提交改動 / 待處理 stash |
246
+ | `workspace` | string | 見 §2.1 | check-out 所在目錄 |
247
+
248
+ 執行:`fossil close [-f]`
249
+
250
+ 成功:`(no output)`(fossil 不列印任何內容)。
251
+
252
+ 失敗示例(有未提交改動,末尾會自動附加提示):
253
+
254
+ ```
255
+ ERROR: Fossil command failed (exit code 1).
256
+ there are unsaved changes in the current check-out
257
+ COMMAND: fossil close
258
+ WORKSPACE: /tmp/tc
259
+
260
+ HINT: the check-out has uncommitted changes; call this tool again with force: true to close anyway.
261
+ ```
262
+
263
+ 失敗示例(本來就沒有開啟的 check-out):
264
+
265
+ ```
266
+ ERROR: Fossil command failed (exit code 1).
267
+ current directory is not within an open check-out
268
+ COMMAND: fossil close -f
269
+ WORKSPACE: /tmp/adoc/ws
270
+ ```
271
+
272
+ > 有未提交改動(用 `-c v` 組 add/modify 過檔案)時關閉需要 `force: true`;剛 open 完直接 close 則不需要。
273
+
274
+ ### 3.4 `fossil_clone`
275
+
276
+ 克隆遠端(`http(s)://`、`ssh://`)或本地倉庫到目標 `.fossil` 檔案。使用網路超時(預設 600s)。
277
+
278
+ | 參數 | 類型 | 必填/預設 | 說明 |
279
+ | --- | --- | --- | --- |
280
+ | `repository_uri` | string | **必填** | 源倉庫 URL 或本地路徑 |
281
+ | `target_file` | string | **必填** | 目標 `.fossil`;**相對路徑以 workspace 為基準**,父目錄自動建立 |
282
+ | `http_proxy` | string | — | 傳給 `--proxy` |
283
+ | `httpauth` | string | — | `user:pass`,傳給 `-B` |
284
+ | `ssl_identity` | string | — | SSL 客戶端憑證檔(`--ssl-identity`) |
285
+ | `ssh_command` | string | — | 當作 ssh 客戶端的命令(`-c`) |
286
+ | `workdir` | string | — | 同時在這個目錄開 check-out(`--workdir`) |
287
+ | `admin_user` | string | — | 把這個使用者設為管理員(`-A`) |
288
+ | `nested` / `once` / `private` / `unversioned` / `verbose` | boolean | `false` | `--nested` / `--once` / `--private` / `-u` / `-v` |
289
+ | `reveal_secrets` | boolean | `false` | 原樣返回輸出中的憑據 |
290
+ | `workspace` | string | 見 §2.1 | 命令執行目錄 |
291
+
292
+ 先 `mkdir -p dirname(targetFile)`,再以 cwd = workspace 執行
293
+ `fossil clone <uri> <abs targetFile> [--proxy P] [--httpauth U:P] [--ssl-identity F] [-c SSH] [--workdir DIR] [-A USER] [--nested] [--once] [--private] [-u] [-v]`。
294
+
295
+ 成功:
296
+
297
+ ```
298
+ Repository cloned into /tmp/ws2/copy.fossil
299
+ Rebuilding repository meta-data...
300
+ 0.0% complete... 100.0% complete...
301
+ Extra delta compression... none found
302
+ …
303
+
304
+ Repository cloned to '/tmp/ws2/copy.fossil'.
305
+ ```
306
+
307
+ 注意:
308
+
309
+ - 克隆完要用得再 `fossil_open`(`repository` 指向該檔案)。
310
+ - 目標檔案存在時 fossil 報錯(`file already exists: …`)。
311
+ - 目標檔案的父目錄會自動建立;`reveal_secrets` 同樣只影響密碼脫敏(clone 通常不列印密碼)。
312
+
313
+ ### 3.5 `fossil_settings`
314
+
315
+ 讀 / 寫 Fossil 設定。
316
+
317
+ | 參數 | 類型 | 必填/預設 | 說明 |
318
+ | --- | --- | --- | --- |
319
+ | `name` | string | — | 設定名(預設**前綴匹配**,`exact` 時精確匹配) |
320
+ | `value` | string | — | 新值;**必須同時給 `name`**,否則返回用法錯誤 |
321
+ | `unset` | boolean | `false` | 清除該設定(`fossil unset <name>`);**必須同時給 `name`**,與 `value` 互斥 |
322
+ | `global` | boolean | `false` | `--global`:讀寫使用者級配置(`~/.config/fossil.db`)而不是倉庫 |
323
+ | `exact` | boolean | `false` | `--exact`:只匹配完全同名的設定 |
324
+ | `workspace` | string | 見 §2.1 | check-out / workspace 目錄 |
325
+
326
+ 這些參數都是選填,呼叫時至少要給 `name` 才能指定設定。
327
+
328
+ 參數組合與執行:
329
+
330
+ | 入參 | 執行的命令 | 結果 |
331
+ | --- | --- | --- |
332
+ | 都省略 | `fossil settings` | 列出所有設定(倉庫級顯示 `(local)`) |
333
+ | 僅 `name` | `fossil settings <name>` | 顯示該設定;格式 `<name> (local) <value>` |
334
+ | `name` + `value` | `fossil settings <name> <value>` | 無輸出(工具顯示 `(no output)`) |
335
+ | `name` + `unset: true` | `fossil unset <name>` | 無輸出,note 說明已清除 |
336
+ | `global: true` | 追加 `--global`(可疊加任意組合) | 讀 / 寫 / 清除使用者級配置 |
337
+ | `exact: true` | 追加 `--exact`(可疊加任意組合) | 只命中同名設定 |
338
+ | 僅 `value` | 不執行 fossil | `isError: true`:`value` requires `name` |
339
+ | `unset` 無 `name` | 不執行 fossil | `isError: true`:`unset` requires `name` |
340
+ | `unset` + `value` | 不執行 fossil | `isError: true`:兩者互斥 |
341
+
342
+ 真實輸出(`name: crlf-glob`):
343
+
344
+ ```
345
+ crlf-glob (local) *
346
+ ```
347
+
348
+ `name: autosync`(前綴匹配會帶出 `autosync-tries`,工具會附加 NOTE;`exact: true` 時只讀一行、無 NOTE):
349
+
350
+ ```
351
+ autosync (local) 1
352
+ autosync-tries
353
+
354
+ NOTE: 'autosync' matched 2 settings (Fossil matches setting names by prefix; pass exact: true to match one).
355
+ ```
356
+
357
+ `name: autosync` + `unset: true`:
358
+
359
+ ```
360
+ (no output)
361
+
362
+ Setting 'autosync' cleared.
363
+ ```
364
+
365
+ 無參數(節選):
366
+
367
+ ```
368
+ access-log (local) 1
369
+ admin-log (local) 1
370
+ autosync (local) 0
371
+ binary-glob (local) *.pcsave,*.png,*.jpg,*.zip,*.exe,*.dll,*.tar.gz
372
+ ```
373
+
374
+ 注意:
375
+
376
+ - 在**沒有 check-out 的目錄**執行時,讀寫的是 fossil 的**使用者級全域性配置**(`~/.config/fossil.db`,
377
+ 可用 `FOSSIL_HOME` 重定向),輸出裡標記為 `(global)`。工具會檢測 `.fslckout` / `_FOSSIL_`,缺失時附加警告
378
+ (`global: true` 時省略該警告,因為你已明確要求全域性配置):
379
+
380
+ ```
381
+ autosync
382
+
383
+ WARNING: no check-out found in '/tmp/tb' (.fslckout / _FOSSIL_ missing), so this setting came from the
384
+ user-level configuration (~/.config/fossil.db), not from a repository.
385
+ ```
386
+
387
+ - 檢測會從 `workspace` **逐級向上**找 `.fslckout` / `_FOSSIL_`(與 fossil 自身定位 check-out 的方式一致),
388
+ 所以 `workspace` 是 check-out 的子目錄時同樣識別得到;警告文字會給出實際檢查的目錄。
389
+ - `name` 預設是 fossil 的前綴匹配;命中多條時工具以 `NOTE` 說明條數,`exact: true` 只命中同名設定。
390
+ - `global: true` 讀寫的是 `~/.config/fossil.db`:`fossil settings --global <name>` 給出不帶 `(local)` 的值,
391
+ `fossil unset <name> --global` 清除全域性配置項。
392
+
393
+ ---
394
+ ### 3.6 `fossil_remote`
395
+
396
+ ```bash
397
+ fossil remote list
398
+ fossil remote
399
+ fossil remote add <name> <url>
400
+ fossil remote delete <name>
401
+ fossil remote <name> # 設為預設
402
+ fossil remote off # 取消預設
403
+ ```
404
+
405
+ | 參數 | 類型 | 必填/預設 | 說明 |
406
+ | --- | --- | --- | --- |
407
+ | `action` | `list` / `default` / `add` / `delete` / `off` / `set` | `list` | `set` 把 `name` 設為預設遠端 |
408
+ | `name` | string | `add` / `delete` / `set` 時必填 | `add` / `delete` 的遠端名;`set` 用遠端名或 URL |
409
+ | `url` | string | `add` 時必填 | `add` 要註冊的 URL |
410
+ | `reveal_secrets` | boolean | `false` | 原樣顯示輸出裡的憑據 |
411
+ | `workspace` | string | 見 admin §2.1 | — |
412
+
413
+ 各 action 對應的 argv 與輸出:
414
+
415
+ | `action` | fossil 命令 | 成功且無輸出時 |
416
+ | --- | --- | --- |
417
+ | `list` | `fossil remote list` | `No remote URLs configured.` |
418
+ | `default` | `fossil remote` | 印出 URL;fossil 印 `off` 時工具改寫成 `No default remote (off).` |
419
+ | `add` | `fossil remote add <name> <url>` | `Remote \`add\` done.` |
420
+ | `delete` | `fossil remote delete <name>` | `Remote \`delete\` done.` |
421
+ | `off` | `fossil remote off` | `Remote \`off\` done.` |
422
+ | `set` | `fossil remote <name>` | `Remote \`set\` done.` |
423
+
424
+ `add` 缺 `name` 或 `url`、`delete`/`set` 缺 `name` 時工具直接返回 `isError`,不 spawn fossil。
425
+ `fossil remote add default <url>` 會被 fossil 拒絕(`rc=1`,提示 `update the "default" remote-url with
426
+ 'fossil remote REF'`),工具同樣先攔下並說明改用 `add` + `set`。
427
+
428
+ 真實輸出:
429
+
430
+ ```
431
+ $ fossil remote list
432
+ origin https://example.com/x.fossil
433
+
434
+ $ fossil remote
435
+ off
436
+
437
+ $ fossil remote origin && fossil remote
438
+ https://example.com/x.fossil
439
+ ```
440
+
441
+ `fossil remote list` 列出的是命名 URL;預設遠端是另一個獨立狀態,`off` 只清預設、不動命名 URL。
442
+ 刪除不存在的名字時 fossil 以成功結束,工具照常返回 `Remote \`delete\` done.`
443
+
444
+ ---
445
+
446
+ ### 3.7 `fossil_push` / `fossil_pull` / `fossil_sync`
447
+
448
+ ```bash
449
+ fossil push [URL] [--all] [--private] [--once] [--verily] [-v] [--proxy P] [--httpauth U:P] [--ssl-identity F]
450
+ fossil pull [URL] [--from-parent-project] [--project-code CODE] …同上的網路選項
451
+ fossil sync [URL] [--unversioned] …同上的網路選項
452
+ ```
453
+
454
+ | 參數 | 類型 | 必填/預設 | 說明 |
455
+ | --- | --- | --- | --- |
456
+ | `url` | string | — | 遠端 URL;省略時沿用 fossil 上次 clone/push/pull/remote/sync 記住的 |
457
+ | `all` | boolean | `false` | `--all` 對所有已設定的遠端操作 |
458
+ | `private` | boolean | `false` | `--private` 一併傳輸私有分支 |
459
+ | `once` | boolean | `false` | `--once` 只用這次,不記住 URL |
460
+ | `verily` | boolean | `false` | `--verily` 與遠端交換額外資訊,確認沒有漏掉內容 |
461
+ | `verbose` | boolean | `false` | `-v` 額外除錯輸出 |
462
+ | `proxy` | string | — | `--proxy` |
463
+ | `httpauth` | string | — | `--httpauth` 的 `USER:PASS` |
464
+ | `ssl_identity` | string | — | `--ssl-identity` |
465
+ | `reveal_secrets` | boolean | `false` | 原樣顯示輸出裡的憑據 |
466
+ | `workspace` | string | 見 §2.1 | — |
467
+
468
+ 三個工具共用的網路選項相同,另有各自專屬的參數:
469
+
470
+ | 工具 | 專屬參數 |
471
+ | --- | --- |
472
+ | `fossil_push` | — |
473
+ | `fossil_pull` | `from_parent_project`(`--from-parent-project`)、`project_code`(`--project-code`) |
474
+ | `fossil_sync` | `unversioned`(`--unversioned`) |
475
+
476
+ 真實輸出:
477
+
478
+ ```
479
+ $ fossil push file:///tmp/target.fossil
480
+ Round-trips: 1 Artifacts sent: 2 received: 0
481
+ Push done, wire bytes sent: 599 received: 302 remote:
482
+ ```
483
+
484
+ fossil 用 `\r` 覆寫同一行進度,因此 `Round-trips:` 可能連續出現多次;成功判定看最後一行
485
+ `Push done` / `Pull done` / `Sync done`。這三個工具用 600s 的 `FOSSIL_NETWORK_TIMEOUT_MS`。
486
+
487
+ 推到**不同專案**的倉庫時 fossil 只印 `Error: wrong project`,仍以 `rc=0` 結束,工具照常返回該輸出。
488
+
489
+ ---
490
+
491
+ ### 3.8 `fossil_rebuild`
492
+
493
+ ```bash
494
+ fossil rebuild [--ifneeded] [--compress] [--compress-only] [--vacuum] [--stats]
495
+ [--analyze] [--wal] [--force] [--quiet] [--index] [--noindex]
496
+ [--pagesize N] [<repository>]
497
+ ```
498
+
499
+ | 參數 | 類型 | 必填/預設 | 說明 |
500
+ | --- | --- | --- | --- |
501
+ | `repository` | string | 目前 check-out 的倉庫 | 要重建的倉庫檔;省略時由 check-out 決定 |
502
+ | `ifneeded` | boolean | `false` | 只在 schema 版本會改變時重建(`--ifneeded`) |
503
+ | `compress` / `compress_only` | boolean | `false` | 一邊重建一邊壓縮 / 只做壓縮 |
504
+ | `vacuum` / `analyze` | boolean | `false` | 重建後 `VACUUM` / `ANALYZE` |
505
+ | `stats` | boolean | `false` | 印出工件統計(`--stats`) |
506
+ | `wal` | boolean | `false` | 改用 WAL 日誌模式(`--wal`) |
507
+ | `force` / `quiet` | boolean | `false` | 有錯誤仍完成 / 只在出錯時輸出 |
508
+ | `index` / `noindex` | boolean | `false` | 建立 / 略過全文索引 |
509
+ | `pagesize` | number | 512..65536 | 資料庫頁大小(`--pagesize`) |
510
+ | `workspace` | string | 見 §2.1 | — |
511
+
512
+ 重建會改寫整個倉庫資料庫;先取得使用者確認再呼叫。
513
+
514
+ 真實輸出(`ifneeded: true`、schema 已是最新):
515
+
516
+ ```
517
+ $ fossil rebuild --ifneeded
518
+ (無輸出,exit 0)
519
+ ```
520
+
521
+ 帶 `compress: true` 時會多印一行壓縮結果:
522
+
523
+ ```
524
+ $ fossil rebuild --compress --quiet
525
+ Extra delta compression... none found
526
+ ```
527
+
528
+ ### 3.9 `fossil_config`
529
+
530
+ ```bash
531
+ fossil config export <area> <file>
532
+ fossil config import|merge <file>
533
+ fossil config pull|push <area> [<url>] [--overwrite]
534
+ fossil config reset <area>
535
+ ```
536
+
537
+ | 參數 | 類型 | 必填/預設 | 說明 |
538
+ | --- | --- | --- | --- |
539
+ | `action` | enum | **必填** | `export` / `import` / `merge` / `pull` / `push` / `reset` |
540
+ | `area` | enum | `export` / `pull` / `push` / `reset` 時必填 | `all` / `email` / `interwiki` / `project` / `shun` / `skin` / `ticket` / `user` / `alias` / `subscriber` |
541
+ | `file` | string | `export` / `import` / `merge` 時必填 | 要寫出或讀入的檔案 |
542
+ | `url` | string | 預設遠端 | `pull`/`push` 的來源或目的 |
543
+ | `overwrite` | boolean | `false` | `pull` 時以遠端內容覆蓋本地設定(`--overwrite`) |
544
+ | `workspace` | string | 見 §2.1 | — |
545
+
546
+ 缺少 `area` 或 `file` 時工具直接報錯:
547
+
548
+ ```
549
+ ERROR: `export` requires `file`.
550
+ ERROR: `reset` requires `area`.
551
+ ```
552
+
553
+ 真實輸出(`action: 'export'`、`area: 'ticket'`):
554
+
555
+ ```
556
+ $ fossil config export ticket /tmp/ticket-config.txt
557
+ (無輸出,exit 0)
558
+ $ head -3 /tmp/ticket-config.txt
559
+ # The "ticket" configuration exported from
560
+ # repository "/tmp/pw/repo.fossil"
561
+ # on 2026-11-17 02:53:53
562
+ ```
563
+
564
+ `pull` / `push` 走 600s 網路超時,其餘動作走一般超時。
565
+
566
+ ## 4. 典型流程
567
+
568
+ ```text
569
+ # 全新專案(倉庫位置由呼叫方顯式給出)
570
+ fossil_init { repository: "/srv/repos/app.fossil", project_name: "app" }
571
+ fossil_open { repository: "/srv/repos/app.fossil", force: true }
572
+ # 之後用 -c v 組:fossil_add / fossil_commit / …
573
+ # 從既有 .gitignore 產生忽略規則:fossil_ignore_from_gitignore { write: true }(-c v 組)
574
+
575
+ # 從遠端開始
576
+ fossil_clone { repository_uri: "https://…/app.fossil", target_file: "app.fossil" }
577
+ fossil_open { repository: "app.fossil", force: true }
578
+
579
+ # 與遠端同步
580
+ fossil_remote { action: "add", name: "origin", url: "https://…/app.fossil" }
581
+ fossil_remote { action: "set", name: "origin" }
582
+ fossil_push {}
583
+ fossil_pull {}
584
+ fossil_sync {}
585
+
586
+ # 收工
587
+ fossil_close { force: true }
588
+ ```
589
+
590
+ 組合能力時(例如 `-c av`)同一程序裡 Admin 與 VCS 工具共用同一個 workspace 預設值,不必每條命令都傳。
591
+
592
+ ---
593
+
594
+ ## 5. 相關配置
595
+
596
+ | 環境變數 | 預設 | 對 Admin 的影響 |
597
+ | --- | --- | --- |
598
+ | `FOSSIL_BIN` | `fossil` | 執行的 fossil 可執行檔案 |
599
+ | `FOSSIL_WORKSPACE` | — | 未傳 `workspace` 且無 `--workspace` 時的預設 workspace(最終兜底 `process.cwd()`) |
600
+ | `FOSSIL_TIMEOUT_MS` | `30000` | init/open/close/settings 超時 |
601
+ | `FOSSIL_NETWORK_TIMEOUT_MS` | `600000` | 網路命令超時:`clone`、`push`/`pull`/`sync`、`config` 的網路動作 |
602
+ | `FOSSIL_MAX_OUTPUT_CHARS` | `120000` | 返回文字截斷閾值 |
603
+ | `FOSSIL_MAX_CAPTURE_BYTES` | `4194304` | 每條流的緩衝上限 |
604
+ | `FOSSIL_HOME` | — | fossil 自身的使用者配置目錄(影響 `fossil settings` 的全域性配置位置) |
605
+
606
+ 命令列側:`--workspace DIR` 設預設 workspace;`-v/--verbose` 把診斷寫到 stderr。
607
+
608
+ ---
609
+
610
+ ## 6. 設計取捨與已知邊界
611
+
612
+ ### 6.1 已修(0.1.3 起)
613
+
614
+ 以下行為均在此前的版本裡實測復現過,現已在工具層處理:
615
+
616
+ | 原問題 | 現行為 |
617
+ | --- | --- |
618
+ | init 時父目錄不存在 → `SQLITE_CANTOPEN` | init 前 `mkdir -p dirname(repository)` |
619
+ | `fossil_settings` 只給 `value` 時靜默忽略 | 直接返回 `isError`:`value` requires `name`(不 spawn fossil) |
620
+ | `fossil_settings` 在非 check-out 目錄靜默讀寫全域性配置 | 檢測 `.fslckout`/`_FOSSIL_`,缺失時附加 `WARNING`(說明配置來自 `~/.config/fossil.db`) |
621
+ | init/clone 把 admin 初始密碼回傳給模型 | 預設脫敏為 `***`;需要真實值時傳 `reveal_secrets: true` |
622
+ | `fossil_close` 在有未提交改動時報錯但無提示 | 錯誤末尾追加 `HINT: … force: true …` |
623
+ | `settings <name>` 前綴匹配不帶說明 | 命中多條時附加 `NOTE: '<name>' matched N settings …`(`exact: true` 時精確匹配,無 NOTE) |
624
+ | 設定只能寫入當前倉庫、無法清除 | `global: true` 讀寫 `~/.config/fossil.db`;`unset: true` 調 `fossil unset <name>` |
625
+ | workspace 不存在時報 `'fossil' not found in PATH` | 先看 workspace 是否為目錄,給出 `workspace directory '…' does not exist` 與修正提示 |
626
+ | workspace 為 `/` 時 `project_name` 為空 | 兜底為 `project` |
627
+ | `fossil remote add default <url>` 被 fossil 以 `rc=1` 拒絕 | 先在工具層攔下,說明改用 `add` + `set` |
628
+ | `fossil remote` 在沒有預設時只印 `off` | 改寫為 `No default remote (off).` |
629
+ | 遠端 URL 與 clone/push 輸出可能帶 `scheme://user@host` | 預設把 userinfo 換成 `***`;`reveal_secrets: true` 時原樣返回 |
630
+ | `fossil add -v` / `fossil add -n` 只在 `--reset` 下有效 | 只在 `reset: true` 時送 `-v`;缺 `files` 且沒 `reset` 時回 `\`files\` is required unless \`reset\` is true.` |
631
+ | `fossil config` 缺 `area` / `file` 時只給用法 | 先在工具層回 `\`<action>\` requires \`area\`.` / `… requires \`file\`.` |
632
+ | `fossil amend` 沒指定任何變更時無意義 | 回 `pass at least one of \`comment\`, \`author\`, …` |
633
+ | `fossil bisect run` 缺命令 | 回 `\`run\` requires \`command\`.` |
634
+ | `fossil sql` 接受任意語句 | 只放行 `SELECT` / `WITH` / `PRAGMA` / `EXPLAIN`,其餘回 `ERROR: the query must start with …` |
635
+ | `fossil remote delete` 刪不存在的名字仍 `rc=0` | 工具照實回 `Remote delete done.`,文件標明此行為 |
636
+
637
+ ### 6.2 有意為之(不是缺陷)
638
+
639
+ - **倉庫配置歸專案所有**:配置寫在提交的 `.fossil-settings/*` 裡,工具不注入預設值,
640
+ 因此同一個倉庫在任何客戶端上行為一致。
641
+ - **`workdir` 的相對路徑以 `workspace` 為基準**,而不是程序 cwd 或 fossil 預設。理由:整個服務只有
642
+ `workspace` 一個目錄概念,參數必須相對它可預測。
643
+ - **`repository` 沒有任何預設位置**,必須有呼叫方(提示詞)顯式給出。
644
+
645
+ ### 6.3 仍然存在(不在工具層解決)
646
+
647
+ 1. **沒有內建 `ignore-glob` 預設值**:Node 專案要自己提交 `.fossil-settings/ignore-glob`
648
+ (如 `node_modules/`、`dist/`、`.npmrc`),否則 `fossil extras` 會把它們都列出來。
649
+ VCS 組的 `fossil_ignore_from_gitignore` 可以從既有 `.gitignore` 產生這份清單。
650
+ 2. **`fossil_settings` 的寫入是倉庫級還是全域性級由 fossil 決定**:無 check-out 時寫入的是使用者級配置,
651
+ 工具只能警告,不能重定向。
652
+ 3. **`reveal_secrets` 覆蓋 `initial password is "…"` 與 URL 的 `scheme://user@host` 兩種形態**;fossil 若新增其它憑據輸出形態需同步。
653
+
654
+ ## 7. 原始碼位置
655
+
656
+ | 檔案 | 內容 |
657
+ | --- | --- |
658
+ | `src/tools/admin.ts` | 11 個工具的註冊與參數校驗 + `redactSecrets`/`withoutSecrets`、`hasCheckout`、`revealSecretsParam` |
659
+ | `src/core/fossil.ts` | `runFossil`、`resolveWorkspace`、`resolveRepoPath`、渲染函式(`renderOutcome`/`formatFailure`) |
660
+ | `src/config.ts` | 超時/上限、`SERVER_NAME`/`SERVER_VERSION`、預設 workspace |
661
+ | `src/tools/common.ts` | `workspaceParam`、`flag`、`clean`、`pushOption` |
662
+ | `tsconfig.build.json` | 構建配置:`src` → `dist`,只輸出 `.js` |
663
+ | `scripts/smoke.mjs` | Admin 組端到端用例(init → open → settings → clone → close;含巢狀目錄 init、密碼脫敏、`settings` 參數校驗) |