@stellar_ai/mcp_fossil_scm 0.2.1 → 0.2.2

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/prompts.md CHANGED
@@ -7,14 +7,14 @@
7
7
  | --- | --- | --- |
8
8
  | `fossil-review-changes` | 讀 `fossil_status` / `fossil_changes` / `fossil_diff`,分組說明未提交的改動並建議提交訊息 | `v` |
9
9
  | `fossil-commit-workflow` | 用 `fossil_addremove`(先 `dry_run`)暫存、以 `fossil_diff` 確認、`fossil_commit` 提交、`fossil_timeline` 覆核 | `v` |
10
- | `fossil-ignore-conversion` | 先預覽 `.gitignore` → `ignore-glob` 的轉換、逐條讀 `NOTE:`,再寫入檔案並用 `fossil_extras` 驗證 | `v` |
11
- | `fossil-trace-change` | 以 `fossil_whatis` / `fossil_finfo` / `fossil_annotate` / `fossil_timeline` / `fossil_search` / `fossil_describe` 追一條變更的來歷 | `v` |
10
+ | `fossil-trace-change` | 以 `fossil_finfo` / `fossil_annotate` / `fossil_timeline` / `fossil_diff` / `fossil_describe` 追一個檔案的變更來歷 | `v` |
12
11
  | `fossil-bisect-hunt` | 標記 good/bad、反覆 `fossil_bisect` 收斂到出問題的 check-in,最後 `reset` 並 `fossil_update` 復原 | `v` |
12
+ | `fossil-ignore-conversion` | 先預覽 `.gitignore` → `ignore-glob` 的轉換、逐條讀 `NOTE:`,再寫入檔案並回報規則數 | `u` |
13
13
  | `fossil-sync-remote` | 用 `fossil_remote` 設定遠端,依序 `fossil_pull` / `fossil_push` / `fossil_sync` | `a` |
14
- | `fossil-repair-repository` | 用 `fossil_info` / `fossil_sql` 記錄現況,`fossil_rebuild` + `ifneeded: true` 判斷後再重建並比對 | `a` |
14
+ | `fossil-repair-repository` | 以 `fossil_rebuild` 依 `ifneeded` → `stats` → `compress` 判斷與重建,再回報結果 | `a` |
15
15
  | `fossil-ticket-triage` | 讀 `fossil_ticket_list`、分組,再用 `fossil_ticket_update` 更新正在處理的工單狀態 | `t` |
16
16
 
17
- 提示只在對應能力啟用時註冊;伺服器在至少一個提示可用時宣告 `prompts` 能力。
17
+ 每個提示只用一個能力組的工具,`需要的能力` 就是註冊它的條件;伺服器在至少一個提示可用時宣告 `prompts` 能力。
18
18
 
19
19
  ## 呼叫範例
20
20
 
package/docs/tickets.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Tickets 能力(`-c t`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.2.1` 及之後,fossil 2.21 實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.2` 及之後,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`。)
package/docs/utils.md ADDED
@@ -0,0 +1,262 @@
1
+ # Utils 能力(`-c u`)工具說明
2
+
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.2` 及之後。所有行為都在 fossil 2.21 上實測。
4
+
5
+ `-c u` 註冊 7 個工具;要連 VCS 一起用 `-c uv`。
6
+
7
+ ---
8
+
9
+ ## 1. 能力概覽
10
+
11
+ | 工具 | 作用 |
12
+ | --- | --- |
13
+ | `fossil_cat` | `fossil cat <file> [-r REV]` |
14
+ | `fossil_grep` | `fossil grep <pattern> <files>` |
15
+ | `fossil_whatis` | `fossil whatis <name>` |
16
+ | `fossil_ignore_from_gitignore` | 讀 `.gitignore`,寫 `.fossil-settings/ignore-glob` |
17
+ | `fossil_search` | `fossil search [-a] [-n N] [-W WIDTH] <pattern>` |
18
+ | `fossil_artifact` | `fossil artifact <hash>` |
19
+ | `fossil_sql` | `fossil sql --readonly -json <query>` |
20
+
21
+ `fossil_ignore_from_gitignore` 只在 Node 裡轉換檔案內容;`fossil_cat`、`fossil_artifact`、`fossil_sql` 可用 `repository` 直接讀倉庫檔;`fossil_grep`、`fossil_whatis`、`fossil_search` 需要在 check-out 裡執行(見 §2)。除了 `fossil_ignore_from_gitignore`,其餘工具都標記 readOnly。
22
+
23
+ 重建整個倉庫資料庫的 `fossil_rebuild` 列在 Admin 能力。
24
+
25
+ ---
26
+
27
+ ## 2. 通用約定
28
+
29
+ - **`workspace`**:所有工具都接受,語義見 `docs/admin.md` §2.1。
30
+ - **直接讀倉庫檔**:`fossil_cat`、`fossil_artifact`、`fossil_sql` 給 `repository` 時不需要 check-out。
31
+ - **失敗格式** 與 admin 一致:
32
+
33
+ ```
34
+ ERROR: Fossil command failed (exit code 1).
35
+ <fossil stderr/stdout 原文>
36
+ COMMAND: fossil <argv>
37
+ WORKSPACE: /tmp/vd
38
+ ```
39
+
40
+ - **路徑參數原樣傳給 fossil**:以 `-` 開頭的檔名會被當成選項,呼叫方需自己加 `./` 前綴。
41
+
42
+ ---
43
+
44
+ ## 3. 工具
45
+
46
+ ### 3.1 `fossil_cat`
47
+
48
+ ```bash
49
+ fossil cat <file> [-r REV]
50
+ ```
51
+
52
+ 列印檔案內容。`revision` 省略時讀當前 check-out 的版本。
53
+
54
+ | 參數 | 類型 | 必填/預設 | 說明 |
55
+ | --- | --- | --- | --- |
56
+ | `file` | string | **必填** | 要列印的檔案 |
57
+ | `revision` | string | — | 指定 check-in 或版本(`-r`) |
58
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
59
+ | `workspace` | string | 見 admin §2.1 | — |
60
+
61
+ ### 3.2 `fossil_grep`
62
+
63
+ ```bash
64
+ fossil grep [-i] [-c] [-l] [--once] [-v] [-s] [--verbose] <pattern> <files...>
65
+ ```
66
+
67
+ 在檔案的**歷史版本**裡搜尋(由新到舊),不是工作區。
68
+
69
+ | 參數 | 類型 | 必填/預設 | 說明 |
70
+ | --- | --- | --- | --- |
71
+ | `pattern` | string | 必填 | POSIX 延伸正規表示式 |
72
+ | `files` | string[] | 必填,至少 1 | 要搜的檔案 |
73
+ | `ignore_case` | boolean | `false` | `-i` |
74
+ | `count` | boolean | `false` | `-c` 只印匹配檔案數 |
75
+ | `files_with_matches` | boolean | `false` | `-l` 每個匹配檔案印一個 artifact |
76
+ | `once` | boolean | `false` | `--once` 第一次命中就停 |
77
+ | `invert_match` | boolean | `false` | `-v` 只列沒有命中的檔案 |
78
+ | `no_messages` | boolean | `false` | `-s` 靜音讀檔訊息 |
79
+ | `verbose` | boolean | `false` | `--verbose` 邊分析邊回報 |
80
+ | `workspace` | string | 見 admin §2.1 | — |
81
+
82
+ 真實輸出(`fossil grep alpha a.txt`):
83
+
84
+ ```
85
+ == 2026-11-17 02:06 a.txt f3a27a552e checkin 86454b6394
86
+ 1:alpha
87
+ ```
88
+
89
+ 空輸出 → `No matches.`
90
+
91
+ ### 3.3 `fossil_whatis`
92
+
93
+ ```bash
94
+ fossil whatis [-f] [--type ci|t|w|g|e] [-v] <name>
95
+ ```
96
+
97
+ 把名字(標籤、分支、雜湊前綴、檔名)解析成 artifact。
98
+
99
+ | 參數 | 類型 | 必填/預設 | 說明 |
100
+ | --- | --- | --- | --- |
101
+ | `name` | string | 必填 | 要解析的名字 |
102
+ | `file` | boolean | `false` | `-f` 把 `name` 當檔名,查內容雜湊 |
103
+ | `type` | `ci` \| `t` \| `w` \| `g` \| `e` | — | `--type` 只匹配該 artifact 類型 |
104
+ | `verbose` | boolean | `false` | `-v` 附內部 record id |
105
+ | `workspace` | string | 見 admin §2.1 | — |
106
+
107
+ 真實輸出(`name: 'tip'`):
108
+
109
+ ```
110
+ name: tip
111
+ artifact: 86454b6394a3b2d2e2c0e2c7a6ee2f4e0b3b5a1a5f2e0d6a0e0f0a1b2c3d4e5f
112
+ size: 340 bytes
113
+ tags: trunk
114
+ type: Check-in by stellar on 2026-11-17 02:06:59
115
+ comment: second commit
116
+ ```
117
+
118
+ ### 3.4 `fossil_ignore_from_gitignore`
119
+
120
+ 把 `.gitignore` 的規則翻成 `ignore-glob` 認得的 glob 清單,可選擇寫成 `.fossil-settings/ignore-glob`。
121
+
122
+ | 參數 | 類型 | 必填/預設 | 說明 |
123
+ | --- | --- | --- | --- |
124
+ | `source` | string | `.gitignore` | 要轉換的檔案,相對 workspace |
125
+ | `write` | boolean | `false` | 寫入 `.fossil-settings/ignore-glob` |
126
+ | `overwrite` | boolean | `false` | 覆蓋已存在的 `.fossil-settings/ignore-glob` |
127
+ | `workspace` | string | 見 admin §2.1 | — |
128
+
129
+ | `.gitignore` 寫法 | 產出的 glob | 原因 |
130
+ | --- | --- | --- |
131
+ | `# 註解`、空行 | 丟棄 | `ignore-glob` 只有樣式 |
132
+ | `!name` | 略過,並在 `NOTE:` 列出 | `ignore-glob` 沒有否定 |
133
+ | `name` | `name`、`*/name` | 沒有斜線的規則在 git 是任意深度,fossil 比對完整路徑 |
134
+ | `*.log` | `*.log` | 開頭就是萬用字元,fossil 的 `*` 已跨目錄 |
135
+ | `dir/` | `dir` | fossil 命中目錄即略過整個子樹 |
136
+ | `/name` | `name` | 錨定在該 `.gitignore` 所在目錄,前綴沿用目錄名 |
137
+ | `a/**/b` | `a/b`、`a/*/b` | `**` 展開成零層與多層兩條 |
138
+ | 含逗號、空白、引號 | 用 `'…'` 或 `"…"` 包住 | fossil 的清單以空白與逗號分隔 |
139
+
140
+ fossil 的 `*` 會跨越 `/`,所以 `logs/*.log` 也會匹配 `logs/a/b.log`;git 的 `*` 只匹配一層。
141
+
142
+ 真實輸出:
143
+
144
+ ```
145
+ Converted 5 rules from .gitignore into 7 ignore-glob patterns.
146
+
147
+ node_modules
148
+ */node_modules
149
+ *.log
150
+ doc/gen
151
+ doc/*/gen
152
+ dist
153
+ */dist
154
+
155
+ NOTE: `**` in doc/**/gen expanded to 2 patterns.
156
+ NOTE: negation !keep.log skipped: ignore-glob has no negation, so the path stays visible.
157
+ ```
158
+
159
+ `write: true` 時第 2 行是 `Wrote .fossil-settings/ignore-glob.`;檔案落地後立刻生效,`fossil_extras`(VCS 能力)不再列出被忽略的路徑。
160
+
161
+ ### 3.5 `fossil_search`
162
+
163
+ ```bash
164
+ fossil search [-a] [-n N] [-W WIDTH] pattern
165
+ ```
166
+
167
+ | 參數 | 類型 | 必填/預設 | 說明 |
168
+ | --- | --- | --- | --- |
169
+ | `pattern` | string | **必填** | 要搜尋的字詞;全部都要命中 |
170
+ | `all` | boolean | `false` | 輸出全部命中,而不是只給高分者(`--all`) |
171
+ | `limit` | number | — | 最多輸出幾筆(`-n`) |
172
+ | `width` | number | — | 輸出寬度,`0` 表示不折行(`-W`) |
173
+ | `workspace` | string | 見 admin §2.1 | — |
174
+
175
+ 真實輸出:
176
+
177
+ ```
178
+ $ fossil search second
179
+ === 2026-11-17 ===
180
+ 02:24:18 [5f3e19ce7a] *CURRENT* second
181
+ +++ no more data (1) +++
182
+ ```
183
+
184
+ 沒有命中時 fossil 只印 `+++ no more data (0) +++` 並以 0 結束,工具改寫成 `No matches.`。
185
+
186
+ ### 3.6 `fossil_artifact`
187
+
188
+ ```bash
189
+ fossil artifact <ARTIFACT-ID> [-R FILE]
190
+ ```
191
+
192
+ | 參數 | 類型 | 必填/預設 | 說明 |
193
+ | --- | --- | --- | --- |
194
+ | `artifact` | string | **必填** | 工件雜湊,可用唯一前綴 |
195
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
196
+ | `workspace` | string | 見 admin §2.1 | — |
197
+
198
+ 真實輸出(檔案版本工件):
199
+
200
+ ```
201
+ $ fossil artifact 17995fe087b0f2ff8b60d47f4005eb1fbab7aa3bc9e3061b09f4a446a5f5dcb8
202
+ hi
203
+ more
204
+ ```
205
+
206
+ 對 check-in 的雜湊則會印出 manifest 原文(`D`/`F`/`P`/`U` 等卡片行)。
207
+ 雜湊可由 `fossil_finfo { mode: "id" }`(VCS 能力)、`fossil_whatis` 或 `fossil_leaves` 取得。
208
+
209
+ ### 3.7 `fossil_sql`
210
+
211
+ ```bash
212
+ fossil sql --readonly [-R FILE] -json "<query>"
213
+ fossil sql --readonly --no-repository FILE -json "<query>"
214
+ ```
215
+
216
+ | 參數 | 類型 | 必填/預設 | 說明 |
217
+ | --- | --- | --- | --- |
218
+ | `query` | string | **必填** | 以 `SELECT` / `WITH` / `PRAGMA` / `EXPLAIN` 開頭的語句;`LIMIT` 寫在 SQL 裡 |
219
+ | `repository` | string | — | `-R` 指定倉庫檔,例如 `repos/app.fossil`;不需要 check-out |
220
+ | `database` | string | — | 查一般的 SQLite 檔而非倉庫(`--no-repository`),例如 chat 存檔 |
221
+ | `workspace` | string | 見 admin §2.1 | — |
222
+
223
+ 輸出是製表符分隔的表格,最後一行是 `N row(s).`;空結果印 `No rows.`。資料庫以 `--readonly` 開啟,
224
+ `fossil sql` 的錯誤(例如 `no such column: name`)由工具轉成 `isError`。
225
+
226
+ 真實輸出:
227
+
228
+ ```
229
+ $ fossil sql --readonly -json "SELECT count(*) AS n FROM event"
230
+ n
231
+ 2
232
+
233
+ 1 row(s).
234
+ ```
235
+
236
+ 不是 `SELECT` / `WITH` / `PRAGMA` / `EXPLAIN` 開頭的語句在交給 fossil 前就被拒絕:
237
+
238
+ ```
239
+ ERROR: the query must start with SELECT, WITH, PRAGMA or EXPLAIN.
240
+ ```
241
+
242
+ ---
243
+
244
+ ## 4. 已知邊界
245
+
246
+ 1. **`fossil_grep` 搜歷史、`fossil_search` 搜註解**:前者逐版本掃描指定檔案,後者只比對 timeline / event 的
247
+ 註解,不含檔案內容、文件或論壇文章。
248
+ 2. **`ignore-glob` 沒有否定**:`!` 開頭的行只能略過並在 `NOTE:` 說明,被 git 重新納入的檔案在 fossil 仍被忽略。
249
+ 3. **含斜線的樣式在 fossil 會匹配更深的路徑**:`src/*.o` 也命中 `src/a/b.o`。
250
+ 4. **`fossil_ignore_from_gitignore` 一次只讀一個檔案**:子目錄的 `.gitignore` 要另外呼叫,`source` 指到該檔,
251
+ 產出的樣式自動帶上目錄前綴。
252
+
253
+ ---
254
+
255
+ ## 5. 原始碼位置
256
+
257
+ | 檔案 | 內容 |
258
+ | --- | --- |
259
+ | `src/tools/utils.ts` | 7 個工具的註冊、參數 schema、argv 拼裝 |
260
+ | `src/core/sql.ts` | `runSql`(`fossil sql --readonly -json` 的包裝與列轉換) |
261
+ | `src/core/gitignore.ts` | `.gitignore` → `ignore-glob` 的轉換規則 |
262
+ | `src/capabilities.ts` | 能力註冊表(`u` → 本檔案 7 個工具) |