@stellar_ai/mcp_fossil_scm 0.1.3 → 0.2.1

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.
package/docs/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # 文件索引
2
2
 
3
3
  按能力分冊,每冊包含:能力概覽表、通用約定、逐工具的參數表與真實 argv/輸出、典型流程、已知邊界、原始碼位置。
4
- 所有內容在 fossil 2.21 + `@stellar_ai/mcp_fossil_scm@0.1.3` 上實測。
4
+ 所有內容在 fossil 2.21 + `@stellar_ai/mcp_fossil_scm@0.2.1` 上實測。
5
5
 
6
6
  | 文件 | 能力 | `-c` | 工具數 |
7
7
  | --- | --- | --- | --- |
@@ -13,13 +13,13 @@
13
13
  | [chat.md](./chat.md) | 聊天室 | `c` | 4 |
14
14
  | [prompts.md](./prompts.md) | MCP 提示(`prompts/list` / `prompts/get`) | — | 8 |
15
15
 
16
- 合計 65 個工具;`-c A`(大寫)啟用全部。
16
+ 合計 65 個工具;`-c All` 啟用全部。
17
17
 
18
18
  ## 閱讀順序
19
19
 
20
20
  1. [admin.md](./admin.md) §2 —— `workspace` 與 `repository` 兩個概念,所有能力共用,先看這裡。
21
21
  2. [prompts.md](./prompts.md) —— 內建的 MCP 提示,把常用的多步流程寫成一段指示。
22
- 3. 然後按需跳到具體能力分冊。VCS 與內容類能力(`v/f/t/w/c`)以 check-out 為前提;`fossil_sql` 可用 `repository` 直接查詢。
22
+ 3. 然後按需跳到具體能力分冊。VCS 與內容類能力(`v/f/t/w/c`)以 check-out 為前提;只讀工具與 `fossil_sql` 可用 `repository` 直接讀倉庫檔。
23
23
 
24
24
  ## 約定速查
25
25
 
package/docs/admin.md CHANGED
@@ -3,7 +3,7 @@
3
3
  本文件對應 `src/tools/admin.ts`(實現)與 `src/core/fossil.ts`(執行器),描述 `fossil-scm` 在
4
4
  `-c a`(Admin)能力下暴露的 **11 個工具**、它們的確切行為、成功/失敗輸出形態,以及當前已知的邊界問題。
5
5
 
6
- 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後。
6
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.1` 及之後。
7
7
 
8
8
  > 執行要求:Node.js >= 20。包內是編譯後的 `dist/**/*.js`(無 source map、無 `.d.ts`)。
9
9
 
@@ -36,7 +36,7 @@ FOSSIL_WORKSPACE=/path/to/workspace fossil-scm -c a
36
36
  ```
37
37
 
38
38
  此時握手返回的 `serverInfo.name` 為 `fossil-scm-a`,`serverInfo.version` 與 `package.json` 的版本一致
39
- (冒煙測試會校驗)。Admin 組不包含任何 `v`/`f`/`t`/`w`/`c` 組的工具。
39
+ (冒煙測試會校驗)。
40
40
 
41
41
  ---
42
42
 
@@ -62,14 +62,13 @@ FOSSIL_WORKSPACE=/path/to/workspace fossil-scm -c a
62
62
 
63
63
  > `workspace` 既是 fossil 子程序的工作目錄,也是 `repository` 相對路徑的基準目錄。
64
64
 
65
- ### 2.2 `repository`:倉庫位置沒有預設
65
+ ### 2.2 `repository`:倉庫檔案路徑
66
66
 
67
- `fossil_init`、`fossil_open` 的倉庫檔案位置**沒有任何預設值**(沒有 `.fossil_repositories` 目錄、不派生
68
- 專案名檔名、不自作主張補 `.fossil` 後綴),必須由提示詞顯式給出:
67
+ `fossil_init`、`fossil_open` 的倉庫檔案位置由呼叫方給出,路徑原樣使用:
69
68
 
70
69
  | 參數 | 類型 | 必填/預設 | 說明 |
71
70
  | --- | --- | --- | --- |
72
- | `repository` | string | **必填** | 倉庫資料庫檔案路徑 |
71
+ | `repository` | string | **必填** | 倉庫資料庫檔案路徑,例如 `repos/app.fossil` |
73
72
 
74
73
  解析規則(`resolveRepoPath`):
75
74
 
@@ -135,6 +134,11 @@ Point `workspace` (or --workspace) at a directory that exists and retry.
135
134
  | --- | --- | --- | --- |
136
135
  | `repository` | string | **必填** | 倉庫檔案路徑,見 §2.2 |
137
136
  | `project_name` | string | workspace 目錄名(根目錄 `/` 時為 `project`) | 寫入倉庫的 `project-name` |
137
+ | `admin_user` | string | 目前使用者 | 記為倉庫管理員的登入名(`-A`) |
138
+ | `template` | string | — | 複製設定來源的倉庫檔(`--template`) |
139
+ | `project_desc` | string | — | 寫入倉庫的專案描述(`--project-desc`) |
140
+ | `date_override` | string | — | 初始 check-in 的時間(`--date-override`) |
141
+ | `sha1` | boolean | `false` | 用 SHA1 而非 SHA3-256 命名 artifact(`--sha1`) |
138
142
  | `reveal_secrets` | boolean | `false` | 原樣返回 admin 初始密碼(預設脫敏為 `***`) |
139
143
  | `workspace` | string | 見 §2.1 | 命令執行目錄 / 相對路徑基準 |
140
144
 
@@ -142,7 +146,8 @@ Point `workspace` (or --workspace) at a directory that exists and retry.
142
146
 
143
147
  ```bash
144
148
  mkdir -p <dirname(repoPath)> # 工具先建父目錄
145
- fossil init <repoPath> --project-name <finalProjectName> # cwd = workspace
149
+ fossil init <repoPath> --project-name <finalProjectName> \ # cwd = workspace
150
+ [-A USER] [--template FILE] [--project-desc TEXT] [--date-override WHEN]
146
151
  ```
147
152
 
148
153
  成功(真實輸出,預設脫敏):
@@ -193,13 +198,20 @@ WORKSPACE: /tmp/ws2
193
198
  | `force` | boolean | `false` | `-f`:目錄非空時仍開啟 |
194
199
  | `keep` | boolean | `false` | `-k`:保留磁碟上已有檔案不動 |
195
200
  | `nested` | boolean | `false` | `--nested`:允許在外層 check-out 內部再開啟一個 check-out |
201
+ | `empty` | boolean | `false` | `--empty`:建立空 check-out,仍與倉庫相連 |
202
+ | `no_sync` | boolean | `false` | `--nosync`:開啟前不自動 sync |
203
+ | `set_mtime` | boolean | `false` | `--setmtime`:把每個檔案的時間戳設成其 check-in 時間 |
204
+ | `force_missing` | boolean | `false` | `--force-missing`:內容缺失時仍開啟 |
196
205
  | `workdir` | string | workspace | `--workdir`;**相對路徑以 workspace 為基準**解析成絕對路徑 |
206
+ | `repodir` | string | — | `repository` 是 URL 時,clone 下來的倉庫放在這個目錄(`--repodir DIR`) |
207
+ | `verbose` | boolean | `false` | `repository` 是 URL 時印出 clone 進度(`--verbose`) |
197
208
  | `workspace` | string | 見 §2.1 | 命令執行目錄 |
198
209
 
199
210
  執行:
200
211
 
201
212
  ```bash
202
- fossil open <repoPath> [-f] [-k] [--nested] [--workdir <abs checkoutDir>] # cwd = workspace
213
+ fossil open <repoPath> [-f] [-k] [--nested] [--empty] [--nosync] [--setmtime] [--force-missing]
214
+ [--workdir <abs checkoutDir>] # cwd = workspace
203
215
  ```
204
216
 
205
217
  `checkoutDir` = `workdir ? resolve(workspace, workdir) : workspace`。
@@ -278,14 +290,18 @@ WORKSPACE: /tmp/adoc/ws
278
290
  | 參數 | 類型 | 必填/預設 | 說明 |
279
291
  | --- | --- | --- | --- |
280
292
  | `repository_uri` | string | **必填** | 源倉庫 URL 或本地路徑 |
281
- | `target_file` | string | **必填** | 目標 `.fossil`;**相對路徑以 workspace 為基準**,父目錄自動建立 |
293
+ | `target_file` | string | **必填** | 目標倉庫檔,例如 `repos/app.fossil`;**相對路徑以 workspace 為基準**,父目錄自動建立 |
282
294
  | `http_proxy` | string | — | 傳給 `--proxy` |
283
295
  | `httpauth` | string | — | `user:pass`,傳給 `-B` |
284
296
  | `ssl_identity` | string | — | SSL 客戶端憑證檔(`--ssl-identity`) |
285
297
  | `ssh_command` | string | — | 當作 ssh 客戶端的命令(`-c`) |
298
+ | `transport_command` | string | — | 搬運訊息到遠端再搬回來的外部命令(`--transport-command`) |
286
299
  | `workdir` | string | — | 同時在這個目錄開 check-out(`--workdir`) |
287
300
  | `admin_user` | string | — | 把這個使用者設為管理員(`-A`) |
288
301
  | `nested` / `once` / `private` / `unversioned` / `verbose` | boolean | `false` | `--nested` / `--once` / `--private` / `-u` / `-v` |
302
+ | `no_compress` | boolean | `false` | 省掉額外的 delta 壓縮(`--nocompress`) |
303
+ | `no_open` | boolean | `false` | 只克隆,不開 check-out(`--no-open`) |
304
+ | `save_http_password` | boolean | `false` | 記住 HTTP 密碼,之後不再詢問(`--save-http-password`) |
289
305
  | `reveal_secrets` | boolean | `false` | 原樣返回輸出中的憑據 |
290
306
  | `workspace` | string | 見 §2.1 | 命令執行目錄 |
291
307
 
@@ -323,8 +339,6 @@ Repository cloned to '/tmp/ws2/copy.fossil'.
323
339
  | `exact` | boolean | `false` | `--exact`:只匹配完全同名的設定 |
324
340
  | `workspace` | string | 見 §2.1 | check-out / workspace 目錄 |
325
341
 
326
- 這些參數都是選填,呼叫時至少要給 `name` 才能指定設定。
327
-
328
342
  參數組合與執行:
329
343
 
330
344
  | 入參 | 執行的命令 | 結果 |
@@ -446,7 +460,7 @@ https://example.com/x.fossil
446
460
  ### 3.7 `fossil_push` / `fossil_pull` / `fossil_sync`
447
461
 
448
462
  ```bash
449
- fossil push [URL] [--all] [--private] [--once] [--verily] [-v] [--proxy P] [--httpauth U:P] [--ssl-identity F]
463
+ fossil push [URL] [--all] [--private] [--once] [--verily] [-v] [--proxy P] [--httpauth U:P] [--ssl-identity F] [-R REPO] [--transport-command CMD] [--no-http-compression] [--ipv4]
450
464
  fossil pull [URL] [--from-parent-project] [--project-code CODE] …同上的網路選項
451
465
  fossil sync [URL] [--unversioned] …同上的網路選項
452
466
  ```
@@ -462,6 +476,10 @@ fossil sync [URL] [--unversioned] …同上的網路選項
462
476
  | `proxy` | string | — | `--proxy` |
463
477
  | `httpauth` | string | — | `--httpauth` 的 `USER:PASS` |
464
478
  | `ssl_identity` | string | — | `--ssl-identity` |
479
+ | `transport_command` | string | — | 搬運訊息到遠端再搬回來的外部命令(`--transport-command`) |
480
+ | `repository` | string | check-out 的倉庫 | 直接指定要操作的倉庫檔(`-R`) |
481
+ | `no_http_compression` | boolean | `false` | HTTP 流量不壓縮(`--no-http-compression`) |
482
+ | `ipv4` | boolean | `false` | 連線只用 IPv4(`--ipv4`) |
465
483
  | `reveal_secrets` | boolean | `false` | 原樣顯示輸出裡的憑據 |
466
484
  | `workspace` | string | 見 §2.1 | — |
467
485
 
@@ -493,12 +511,12 @@ fossil 用 `\r` 覆寫同一行進度,因此 `Round-trips:` 可能連續出現
493
511
  ```bash
494
512
  fossil rebuild [--ifneeded] [--compress] [--compress-only] [--vacuum] [--stats]
495
513
  [--analyze] [--wal] [--force] [--quiet] [--index] [--noindex]
496
- [--pagesize N] [<repository>]
514
+ [--cluster] [--deanalyze] [--noverify] [--pagesize N] [<repository>]
497
515
  ```
498
516
 
499
517
  | 參數 | 類型 | 必填/預設 | 說明 |
500
518
  | --- | --- | --- | --- |
501
- | `repository` | string | 目前 check-out 的倉庫 | 要重建的倉庫檔;省略時由 check-out 決定 |
519
+ | `repository` | string | 目前 check-out 的倉庫 | 要重建的倉庫檔,例如 `repos/app.fossil`;省略時由 check-out 決定 |
502
520
  | `ifneeded` | boolean | `false` | 只在 schema 版本會改變時重建(`--ifneeded`) |
503
521
  | `compress` / `compress_only` | boolean | `false` | 一邊重建一邊壓縮 / 只做壓縮 |
504
522
  | `vacuum` / `analyze` | boolean | `false` | 重建後 `VACUUM` / `ANALYZE` |
@@ -506,6 +524,9 @@ fossil rebuild [--ifneeded] [--compress] [--compress-only] [--vacuum] [--stats]
506
524
  | `wal` | boolean | `false` | 改用 WAL 日誌模式(`--wal`) |
507
525
  | `force` / `quiet` | boolean | `false` | 有錯誤仍完成 / 只在出錯時輸出 |
508
526
  | `index` / `noindex` | boolean | `false` | 建立 / 略過全文索引 |
527
+ | `cluster` | boolean | `false` | 為未分叢的工件計算分叢(`--cluster`) |
528
+ | `deanalyze` | boolean | `false` | 移除資料庫裡的 ANALYZE 表(`--deanalyze`) |
529
+ | `no_verify` | boolean | `false` | 不驗證 BLOB 表的變更(`--noverify`) |
509
530
  | `pagesize` | number | 512..65536 | 資料庫頁大小(`--pagesize`) |
510
531
  | `workspace` | string | 見 §2.1 | — |
511
532
 
@@ -540,6 +561,7 @@ fossil config reset <area>
540
561
  | `area` | enum | `export` / `pull` / `push` / `reset` 時必填 | `all` / `email` / `interwiki` / `project` / `shun` / `skin` / `ticket` / `user` / `alias` / `subscriber` |
541
562
  | `file` | string | `export` / `import` / `merge` 時必填 | 要寫出或讀入的檔案 |
542
563
  | `url` | string | 預設遠端 | `pull`/`push` 的來源或目的 |
564
+ | `repository` | string | check-out 的倉庫 | 直接指定要設定哪個倉庫檔(`-R`) |
543
565
  | `overwrite` | boolean | `false` | `pull` 時以遠端內容覆蓋本地設定(`--overwrite`) |
544
566
  | `workspace` | string | 見 §2.1 | — |
545
567
 
@@ -609,11 +631,11 @@ fossil_close { force: true }
609
631
 
610
632
  ## 6. 設計取捨與已知邊界
611
633
 
612
- ### 6.1 已修(0.1.3 起)
634
+ ### 6.1 工具層補強
613
635
 
614
- 以下行為均在此前的版本裡實測復現過,現已在工具層處理:
636
+ `src/tools/admin.ts` 在 fossil 之外補上這些行為:
615
637
 
616
- | 原問題 | 現行為 |
638
+ | 情境 | 工具行為 |
617
639
  | --- | --- |
618
640
  | init 時父目錄不存在 → `SQLITE_CANTOPEN` | init 前 `mkdir -p dirname(repository)` |
619
641
  | `fossil_settings` 只給 `value` 時靜默忽略 | 直接返回 `isError`:`value` requires `name`(不 spawn fossil) |
@@ -627,28 +649,21 @@ fossil_close { force: true }
627
649
  | `fossil remote add default <url>` 被 fossil 以 `rc=1` 拒絕 | 先在工具層攔下,說明改用 `add` + `set` |
628
650
  | `fossil remote` 在沒有預設時只印 `off` | 改寫為 `No default remote (off).` |
629
651
  | 遠端 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
652
  | `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
653
  | `fossil remote delete` 刪不存在的名字仍 `rc=0` | 工具照實回 `Remote delete done.`,文件標明此行為 |
636
654
 
637
- ### 6.2 有意為之(不是缺陷)
655
+ ### 6.2 設計取捨
638
656
 
639
- - **倉庫配置歸專案所有**:配置寫在提交的 `.fossil-settings/*` 裡,工具不注入預設值,
640
- 因此同一個倉庫在任何客戶端上行為一致。
641
- - **`workdir` 的相對路徑以 `workspace` 為基準**,而不是程序 cwd 或 fossil 預設。理由:整個服務只有
642
- `workspace` 一個目錄概念,參數必須相對它可預測。
643
- - **`repository` 沒有任何預設位置**,必須有呼叫方(提示詞)顯式給出。
657
+ - **倉庫配置歸專案所有**:配置寫在提交的 `.fossil-settings/*` 裡,同一個倉庫在任何客戶端上行為一致。
658
+ - **`workdir` 的相對路徑以 `workspace` 為基準**:整個服務只有 `workspace` 一個目錄概念,路徑相對它才可預測。
659
+ - **倉庫檔案位置由呼叫方給出**:`fossil_init`、`fossil_open`、`fossil_rebuild` 的 `repository` 指向明確的檔案。
644
660
 
645
661
  ### 6.3 仍然存在(不在工具層解決)
646
662
 
647
663
  1. **沒有內建 `ignore-glob` 預設值**:Node 專案要自己提交 `.fossil-settings/ignore-glob`
648
664
  (如 `node_modules/`、`dist/`、`.npmrc`),否則 `fossil extras` 會把它們都列出來。
649
665
  VCS 組的 `fossil_ignore_from_gitignore` 可以從既有 `.gitignore` 產生這份清單。
650
- 2. **`fossil_settings` 的寫入是倉庫級還是全域性級由 fossil 決定**:無 check-out 時寫入的是使用者級配置,
651
- 工具只能警告,不能重定向。
666
+ 2. **`fossil_settings` 的寫入層級由 fossil 決定**:無 check-out 時寫入使用者級配置,工具以 `WARNING` 指出實際位置。
652
667
  3. **`reveal_secrets` 覆蓋 `initial password is "…"` 與 URL 的 `scheme://user@host` 兩種形態**;fossil 若新增其它憑據輸出形態需同步。
653
668
 
654
669
  ## 7. 原始碼位置
package/docs/chat.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Chat 能力(`-c c`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後,fossil 2.21 實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.1` 及之後,fossil 2.21 實測。
4
4
 
5
5
  `-c c` 註冊 4 個工具:`fossil_chat_url` / `fossil_chat_send` / `fossil_chat_pull` / `fossil_chat_read`。
6
6
 
package/docs/forum.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Forum 能力(`-c f`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後,fossil 2.21 實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.1` 及之後,fossil 2.21 實測。
4
4
 
5
5
  `-c f` 註冊 3 個工具,**全部只讀**:`fossil_forum_list` / `fossil_forum_read` / `fossil_forum_search`。
6
6
 
package/docs/tickets.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Tickets 能力(`-c t`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後,fossil 2.21 實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.1` 及之後,fossil 2.21 實測。
4
4
 
5
5
  `-c t` 註冊 4 個工具:`fossil_ticket_list` / `fossil_ticket_show` / `fossil_ticket_create` / `fossil_ticket_update`。
6
6
  (check-out 用 admin 的 `fossil_init` / `fossil_open`,組合啟用寫 `-c at`。)