@stellar_ai/mcp_fossil_scm 0.1.3 → 0.2.0

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.0` 上實測。
5
5
 
6
6
  | 文件 | 能力 | `-c` | 工具數 |
7
7
  | --- | --- | --- | --- |
@@ -13,7 +13,7 @@
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
 
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.0` 及之後。
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,10 +62,9 @@ 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
  | --- | --- | --- | --- |
@@ -135,6 +134,10 @@ 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`) |
138
141
  | `reveal_secrets` | boolean | `false` | 原樣返回 admin 初始密碼(預設脫敏為 `***`) |
139
142
  | `workspace` | string | 見 §2.1 | 命令執行目錄 / 相對路徑基準 |
140
143
 
@@ -142,7 +145,8 @@ Point `workspace` (or --workspace) at a directory that exists and retry.
142
145
 
143
146
  ```bash
144
147
  mkdir -p <dirname(repoPath)> # 工具先建父目錄
145
- fossil init <repoPath> --project-name <finalProjectName> # cwd = workspace
148
+ fossil init <repoPath> --project-name <finalProjectName> \ # cwd = workspace
149
+ [-A USER] [--template FILE] [--project-desc TEXT] [--date-override WHEN]
146
150
  ```
147
151
 
148
152
  成功(真實輸出,預設脫敏):
@@ -193,13 +197,18 @@ WORKSPACE: /tmp/ws2
193
197
  | `force` | boolean | `false` | `-f`:目錄非空時仍開啟 |
194
198
  | `keep` | boolean | `false` | `-k`:保留磁碟上已有檔案不動 |
195
199
  | `nested` | boolean | `false` | `--nested`:允許在外層 check-out 內部再開啟一個 check-out |
200
+ | `empty` | boolean | `false` | `--empty`:建立空 check-out,仍與倉庫相連 |
201
+ | `no_sync` | boolean | `false` | `--nosync`:開啟前不自動 sync |
202
+ | `set_mtime` | boolean | `false` | `--setmtime`:把每個檔案的時間戳設成其 check-in 時間 |
203
+ | `force_missing` | boolean | `false` | `--force-missing`:內容缺失時仍開啟 |
196
204
  | `workdir` | string | workspace | `--workdir`;**相對路徑以 workspace 為基準**解析成絕對路徑 |
197
205
  | `workspace` | string | 見 §2.1 | 命令執行目錄 |
198
206
 
199
207
  執行:
200
208
 
201
209
  ```bash
202
- fossil open <repoPath> [-f] [-k] [--nested] [--workdir <abs checkoutDir>] # cwd = workspace
210
+ fossil open <repoPath> [-f] [-k] [--nested] [--empty] [--nosync] [--setmtime] [--force-missing]
211
+ [--workdir <abs checkoutDir>] # cwd = workspace
203
212
  ```
204
213
 
205
214
  `checkoutDir` = `workdir ? resolve(workspace, workdir) : workspace`。
@@ -323,8 +332,6 @@ Repository cloned to '/tmp/ws2/copy.fossil'.
323
332
  | `exact` | boolean | `false` | `--exact`:只匹配完全同名的設定 |
324
333
  | `workspace` | string | 見 §2.1 | check-out / workspace 目錄 |
325
334
 
326
- 這些參數都是選填,呼叫時至少要給 `name` 才能指定設定。
327
-
328
335
  參數組合與執行:
329
336
 
330
337
  | 入參 | 執行的命令 | 結果 |
@@ -493,7 +500,7 @@ fossil 用 `\r` 覆寫同一行進度,因此 `Round-trips:` 可能連續出現
493
500
  ```bash
494
501
  fossil rebuild [--ifneeded] [--compress] [--compress-only] [--vacuum] [--stats]
495
502
  [--analyze] [--wal] [--force] [--quiet] [--index] [--noindex]
496
- [--pagesize N] [<repository>]
503
+ [--cluster] [--deanalyze] [--noverify] [--pagesize N] [<repository>]
497
504
  ```
498
505
 
499
506
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -506,6 +513,9 @@ fossil rebuild [--ifneeded] [--compress] [--compress-only] [--vacuum] [--stats]
506
513
  | `wal` | boolean | `false` | 改用 WAL 日誌模式(`--wal`) |
507
514
  | `force` / `quiet` | boolean | `false` | 有錯誤仍完成 / 只在出錯時輸出 |
508
515
  | `index` / `noindex` | boolean | `false` | 建立 / 略過全文索引 |
516
+ | `cluster` | boolean | `false` | 為未分叢的工件計算分叢(`--cluster`) |
517
+ | `deanalyze` | boolean | `false` | 移除資料庫裡的 ANALYZE 表(`--deanalyze`) |
518
+ | `no_verify` | boolean | `false` | 不驗證 BLOB 表的變更(`--noverify`) |
509
519
  | `pagesize` | number | 512..65536 | 資料庫頁大小(`--pagesize`) |
510
520
  | `workspace` | string | 見 §2.1 | — |
511
521
 
@@ -609,11 +619,11 @@ fossil_close { force: true }
609
619
 
610
620
  ## 6. 設計取捨與已知邊界
611
621
 
612
- ### 6.1 已修(0.1.3 起)
622
+ ### 6.1 工具層補強
613
623
 
614
- 以下行為均在此前的版本裡實測復現過,現已在工具層處理:
624
+ `src/tools/admin.ts` 在 fossil 之外補上這些行為:
615
625
 
616
- | 原問題 | 現行為 |
626
+ | 情境 | 工具行為 |
617
627
  | --- | --- |
618
628
  | init 時父目錄不存在 → `SQLITE_CANTOPEN` | init 前 `mkdir -p dirname(repository)` |
619
629
  | `fossil_settings` 只給 `value` 時靜默忽略 | 直接返回 `isError`:`value` requires `name`(不 spawn fossil) |
@@ -627,28 +637,21 @@ fossil_close { force: true }
627
637
  | `fossil remote add default <url>` 被 fossil 以 `rc=1` 拒絕 | 先在工具層攔下,說明改用 `add` + `set` |
628
638
  | `fossil remote` 在沒有預設時只印 `off` | 改寫為 `No default remote (off).` |
629
639
  | 遠端 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
640
  | `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
641
  | `fossil remote delete` 刪不存在的名字仍 `rc=0` | 工具照實回 `Remote delete done.`,文件標明此行為 |
636
642
 
637
- ### 6.2 有意為之(不是缺陷)
643
+ ### 6.2 設計取捨
638
644
 
639
- - **倉庫配置歸專案所有**:配置寫在提交的 `.fossil-settings/*` 裡,工具不注入預設值,
640
- 因此同一個倉庫在任何客戶端上行為一致。
641
- - **`workdir` 的相對路徑以 `workspace` 為基準**,而不是程序 cwd 或 fossil 預設。理由:整個服務只有
642
- `workspace` 一個目錄概念,參數必須相對它可預測。
643
- - **`repository` 沒有任何預設位置**,必須有呼叫方(提示詞)顯式給出。
645
+ - **倉庫配置歸專案所有**:配置寫在提交的 `.fossil-settings/*` 裡,同一個倉庫在任何客戶端上行為一致。
646
+ - **`workdir` 的相對路徑以 `workspace` 為基準**:整個服務只有 `workspace` 一個目錄概念,路徑相對它才可預測。
647
+ - **倉庫檔案位置由呼叫方給出**:`fossil_init`、`fossil_open`、`fossil_rebuild` 的 `repository` 指向明確的檔案。
644
648
 
645
649
  ### 6.3 仍然存在(不在工具層解決)
646
650
 
647
651
  1. **沒有內建 `ignore-glob` 預設值**:Node 專案要自己提交 `.fossil-settings/ignore-glob`
648
652
  (如 `node_modules/`、`dist/`、`.npmrc`),否則 `fossil extras` 會把它們都列出來。
649
653
  VCS 組的 `fossil_ignore_from_gitignore` 可以從既有 `.gitignore` 產生這份清單。
650
- 2. **`fossil_settings` 的寫入是倉庫級還是全域性級由 fossil 決定**:無 check-out 時寫入的是使用者級配置,
651
- 工具只能警告,不能重定向。
654
+ 2. **`fossil_settings` 的寫入層級由 fossil 決定**:無 check-out 時寫入使用者級配置,工具以 `WARNING` 指出實際位置。
652
655
  3. **`reveal_secrets` 覆蓋 `initial password is "…"` 與 URL 的 `scheme://user@host` 兩種形態**;fossil 若新增其它憑據輸出形態需同步。
653
656
 
654
657
  ## 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.0` 及之後,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.0` 及之後,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.0` 及之後,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`。)