@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/README.md +14 -12
- package/dist/cli.js +11 -11
- package/dist/config.js +1 -1
- package/dist/index.js +1 -1
- package/dist/tools/admin.js +41 -3
- package/dist/tools/version-control.js +468 -90
- package/docs/README.md +2 -2
- package/docs/admin.md +28 -25
- package/docs/chat.md +1 -1
- package/docs/forum.md +1 -1
- package/docs/tickets.md +1 -1
- package/docs/vcs.md +161 -68
- package/docs/wiki.md +1 -1
- package/package.json +1 -1
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.
|
|
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
|
|
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.
|
|
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
|
-
(冒煙測試會校驗)。
|
|
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`
|
|
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>
|
|
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] [--
|
|
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
|
|
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
|
-
-
|
|
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`
|
|
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
package/docs/forum.md
CHANGED
package/docs/tickets.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Tickets 能力(`-c t`)工具說明
|
|
2
2
|
|
|
3
|
-
適用於 `@stellar_ai/mcp_fossil_scm@0.
|
|
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`。)
|