@stellar_ai/mcp_fossil_scm 0.2.0 → 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/vcs.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # VCS 能力(`-c v`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.2.0` 及之後。所有行為都在 fossil 2.21 上實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.2` 及之後。所有行為都在 fossil 2.21 上實測。
4
4
 
5
- `-c v` 註冊 40 個工具;要連 admin 一起用 `-c av`。
5
+ `-c v` 註冊 33 個工具;要連 admin 與 utils 一起用 `-c auv`。
6
6
 
7
7
  ---
8
8
 
@@ -12,9 +12,8 @@
12
12
  | --- | --- |
13
13
  | `fossil_status` | `fossil status` + `fossil extra` |
14
14
  | `fossil_diff` | `fossil diff` |
15
- | `fossil_cat` | `fossil cat <file> [-r REV]` |
16
15
  | `fossil_finfo` | `fossil finfo [-i\|-s\|-p\|-l] <file>` |
17
- | `fossil_ls` | `fossil ls [-r REV] [--age] [-v] [-t] [--hash]` |
16
+ | `fossil_ls` | `fossil ls [-R FILE] [-r REV] [--age] [-v] [-t] [--hash]` |
18
17
  | `fossil_extras` | `fossil extras` |
19
18
  | `fossil_timeline` | `fossil timeline -n N` |
20
19
  | `fossil_info` | `fossil info [target]` |
@@ -33,14 +32,10 @@
33
32
  | `fossil_undo` | `fossil undo [-n]` |
34
33
  | `fossil_changes` | `fossil changes` |
35
34
  | `fossil_annotate` | `fossil blame\|annotate\|praise <file>` |
36
- | `fossil_grep` | `fossil grep <pattern> <files>` |
37
- | `fossil_whatis` | `fossil whatis <name>` |
38
35
  | `fossil_merge_base` | `fossil merge-base <v1> <v2>` |
39
36
  | `fossil_leaves` | `fossil leaves` |
40
37
  | `fossil_descendants` | `fossil descendants [checkin]` |
41
38
  | `fossil_unpublished` | `fossil unpublished` |
42
- | `fossil_search` | `fossil search [-a] [-n N] [-W WIDTH] <pattern>` |
43
- | `fossil_artifact` | `fossil artifact <hash>` |
44
39
  | `fossil_describe` | `fossil describe [version]` |
45
40
  | `fossil_archive` | `fossil tarball\|zip <version> <outfile>` |
46
41
  | `fossil_unversioned` | `fossil unversioned list\|cat\|add\|remove\|touch` |
@@ -48,11 +43,9 @@
48
43
  | `fossil_amend` | `fossil amend <check-in> --comment/--tag/…` |
49
44
  | `fossil_patch` | `fossil patch create\|diff\|apply <file>` |
50
45
  | `fossil_bisect` | `fossil bisect good\|bad\|skip\|next\|log\|chart\|options\|reset\|run` |
51
- | `fossil_sql` | `fossil sql --readonly -json <query>` |
52
- | `fossil_ignore_from_gitignore` | 讀 `.gitignore`,寫 `.fossil-settings/ignore-glob` |
53
46
 
54
47
  標了 `destructiveHint: true` 的是 `fossil_rm` / `fossil_revert` / `fossil_clean` / `fossil_update` / `fossil_undo`:
55
- 它們會覆蓋工作區內容,呼叫方應先確認,或先跑 `dry_run` / `-n` 預覽。除了 `fossil_sql` 可用 `repository` 直接查詢,其餘工具都需要 check-out(見 §2)。
48
+ 它們會覆蓋工作區內容,呼叫方應先確認,或先跑 `dry_run` / `-n` 預覽。`fossil_info`/`fossil_descendants`/`fossil_ls`/`fossil_timeline` 可用 `repository` 直接讀倉庫檔,其餘工具都需要 check-out(見 §2)。原始工件、檔案內容與 SQL 查詢屬於 utils 能力(`-c u`)。
56
49
 
57
50
  ---
58
51
 
@@ -81,13 +74,13 @@ WORKSPACE: /tmp/vd
81
74
 
82
75
  ### 3.1 `fossil_status`
83
76
 
84
- 一次呼叫併發執行兩條命令,輸出分兩段:
77
+ 一次呼叫依序執行兩條命令,輸出分兩段:
85
78
 
86
79
  ```bash
87
80
  fossil status|changes [--dotfiles] [--ignore GLOBS] [--hash] [--abs-paths|--rel-paths]
88
81
  [--edited|--updated|--changed|--missing|--added|--deleted|--renamed|--conflict
89
82
  |--meta|--unchanged|--all|--differ|--extra ...] [--classify] [--header] [-v]
90
- fossil extra [--dotfiles] [--ignore GLOBS] # cwd = workspace,未指定 select 時並行
83
+ fossil extra [--dotfiles] [--ignore GLOBS] # cwd = workspace,未指定 select 時執行
91
84
  ```
92
85
 
93
86
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -128,7 +121,7 @@ comment: first (user: stellar)
128
121
 
129
122
  ```bash
130
123
  fossil diff [--from X] [--to Y] [--branch B] [-ci C] [--brief] [--numstat]
131
- [-c N] [-y] [-v] [--undo] [-w] [-Z] [-i] [--unified] [-h] [--json] [-W N]
124
+ [-c N] [-y] [-v] [--undo] [-w] [-Z] [--strip-trailing-cr] [-N] [-i] [--unified] [-h] [--json] [-W N]
132
125
  [files...]
133
126
  ```
134
127
 
@@ -147,6 +140,8 @@ fossil diff [--from X] [--to Y] [--branch B] [-ci C] [--brief] [--numstat]
147
140
  | `undo` | boolean | `false` | `--undo` 與 undo 緩衝區比較 |
148
141
  | `ignore_whitespace` | boolean | `false` | `-w` 忽略空白差異 |
149
142
  | `ignore_trailing_space` | boolean | `false` | `-Z` 忽略行尾空白差異 |
143
+ | `strip_trailing_cr` | boolean | `false` | `--strip-trailing-cr` 忽略每行結尾的 CR |
144
+ | `new_file` | boolean | `false` | `-N` 把新增檔案視為本來就是空內容 |
150
145
  | `internal` | boolean | `false` | `-i` 用內建 diff |
151
146
  | `unified` | boolean | `false` | `--unified` 輸出 unified patch |
152
147
  | `versions_header` | boolean | `false` | `-h` 在標頭列出比較的版本 |
@@ -157,21 +152,7 @@ fossil diff [--from X] [--to Y] [--branch B] [-ci C] [--brief] [--numstat]
157
152
  不給版本時是“工作區 vs 最近一次 check-in”。版本名寫錯時 fossil 報
158
153
  `cannot resolve name: tip-1`(`tip-1` 不是合法表示式,用雜湊前綴或 `tip`)。空輸出 → `No differences found.`
159
154
 
160
- ### 3.3 `fossil_cat`
161
-
162
- ```bash
163
- fossil cat <file> [-r REV]
164
- ```
165
-
166
- 列印檔案內容。`revision` 省略時讀當前 check-out 的版本。
167
-
168
- | 參數 | 類型 | 必填/預設 | 說明 |
169
- | --- | --- | --- | --- |
170
- | `file` | string | **必填** | 要列印的檔案 |
171
- | `revision` | string | — | 指定 check-in 或版本(`-r`) |
172
- | `workspace` | string | 見 admin §2.1 | — |
173
-
174
- ### 3.4 `fossil_finfo`
155
+ ### 3.3 `fossil_finfo`
175
156
 
176
157
  ```bash
177
158
  fossil finfo [-l|-i|-s|-p] [-b] [-n N] [--offset P] [-r REV] [-v] <file>
@@ -210,7 +191,7 @@ unchanged 5f3e19ce7a
210
191
  `-b` / `-n` / `--offset` 只在 `log` 模式送出,`-r` 只在 `id` 與 `print` 模式送出,`-v` 只在 `id` 模式送出;
211
192
  其餘組合 fossil 會回 `unrecognized command-line option or missing argument`。
212
193
 
213
- ### 3.5 `fossil_extras`
194
+ ### 3.4 `fossil_extras`
214
195
 
215
196
  ```bash
216
197
  fossil extras [--dotfiles] [--ignore GLOBS] [--abs-paths|--rel-paths] [--header] [--case-sensitive 1|0]
@@ -228,10 +209,10 @@ fossil extras [--dotfiles] [--ignore GLOBS] [--abs-paths|--rel-paths] [--header]
228
209
 
229
210
  空輸出 → `No untracked files.`。Node 專案建議提交 `.fossil-settings/ignore-glob`(見 admin §6.3)。
230
211
 
231
- ### 3.6 `fossil_timeline`
212
+ ### 3.5 `fossil_timeline`
232
213
 
233
214
  ```bash
234
- fossil timeline -n <limit> [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [-F FORMAT] [-v]
215
+ fossil timeline -n <limit> [-R FILE] [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [-F FORMAT] [-v]
235
216
  [--offset N] [-W N]
236
217
  ```
237
218
 
@@ -248,6 +229,7 @@ fossil timeline -n <limit> [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [
248
229
  | `verbose` | boolean | `false` | 每個 check-in 後面列出變更的檔案(`-v`) |
249
230
  | `offset` | number | — | 跳過前 N 條(`--offset`) |
250
231
  | `width` | number | — | 輸出寬度(`-W`,≥20) |
232
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
251
233
  | `workspace` | string | 見 admin §2.1 | — |
252
234
 
253
235
  真實輸出(`limit: 3`):
@@ -260,10 +242,10 @@ fossil timeline -n <limit> [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [
260
242
  +++ no more data (3) +++
261
243
  ```
262
244
 
263
- ### 3.7 `fossil_info`
245
+ ### 3.6 `fossil_info`
264
246
 
265
247
  ```bash
266
- fossil info [target] [-v]
248
+ fossil info [target] [-R FILE] [-v]
267
249
  ```
268
250
 
269
251
  `target` 可以是檔名、check-in 雜湊、分支名;省略時給倉庫/check-out 元資訊(真實輸出見 §3.1 的 STATUS 段同源)。
@@ -273,15 +255,16 @@ fossil info [target] [-v]
273
255
  | --- | --- | --- | --- |
274
256
  | `target` | string | — | 檔名、check-in 雜湊或分支名 |
275
257
  | `verbose` | boolean | `false` | 額外資訊,如 SQLite 版本與倉庫大小(`-v`) |
258
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
276
259
  | `workspace` | string | 見 admin §2.1 | — |
277
260
 
278
261
  ---
279
- ### 3.8 `fossil_changes`
262
+ ### 3.7 `fossil_changes`
280
263
 
281
264
  ```bash
282
265
  fossil changes [--edited|--updated|--added|--deleted|--renamed|--conflict|--meta]
283
266
  [--changed|--missing|--unchanged|--extra|--differ|--all]
284
- [--classify] [--no-merge] [--hash] [--header] [-v]
267
+ [--classify] [--no-classify] [--no-merge] [--merge] [--ignore GLOBS] [--hash] [--header] [-v]
285
268
  [--dotfiles] [--abs-paths|--rel-paths] [files...]
286
269
  ```
287
270
 
@@ -294,6 +277,9 @@ fossil changes [--edited|--updated|--added|--deleted|--renamed|--conflict|--meta
294
277
  | `changed` / `missing` / `unchanged` / `extra` / `differ` / `all` | boolean | `false` | 其餘變更類型過濾,可疊加 |
295
278
  | `classify` | boolean | `false` | 每行前面加變更類型 |
296
279
  | `no_merge` | boolean | `false` | 隱藏 merge 貢獻者 |
280
+ | `merge` | boolean | `false` | 只列帶合併衝突標記的檔案(`--merge`) |
281
+ | `no_classify` | boolean | `false` | 不加每行的變更類型(`--no-classify`) |
282
+ | `ignore` | string | — | `--ignore` 的 CSG,符合的檔案不列入 |
297
283
  | `hash` | boolean | `false` | 用雜湊而非大小+mtime 判斷狀態(`--hash`) |
298
284
  | `header` | boolean | `false` | 非空報告前印倉庫名(`--header`) |
299
285
  | `verbose` | boolean | `false` | 空報告時印 `(none)`(`-v`) |
@@ -314,7 +300,7 @@ ADDED src/tools/notes.ts
314
300
  變更偵測靠 mtime + 大小,改動若落在上一次 commit 的同一秒內,`changes` / `status` / `diff` 都還看不到,
315
301
  `touch` 檔案後才出現。
316
302
 
317
- ### 3.9 `fossil_annotate`
303
+ ### 3.8 `fossil_annotate`
318
304
 
319
305
  ```bash
320
306
  fossil blame|annotate|praise <file> [-r REV] [-o ORIGIN] [-n LIMIT] [--filevers] [-l] [-w] [-Z]
@@ -341,64 +327,7 @@ fossil blame|annotate|praise <file> [-r REV] [-o ORIGIN] [-n LIMIT] [--filevers]
341
327
 
342
328
  `fossil blame` 的行是 `<hash> <date> <line>: <text>`,praise/blame 的 `<text>` 是 `作者: 內容`。
343
329
 
344
- ### 3.10 `fossil_grep`
345
-
346
- ```bash
347
- fossil grep [-i] [-c] [-l] [--once] [-v] [-s] [--verbose] <pattern> <files...>
348
- ```
349
-
350
- 在檔案的**歷史版本**裡搜尋(由新到舊),不是工作區。
351
-
352
- | 參數 | 類型 | 必填/預設 | 說明 |
353
- | --- | --- | --- | --- |
354
- | `pattern` | string | 必填 | POSIX 延伸正規表示式 |
355
- | `files` | string[] | 必填,至少 1 | 要搜的檔案 |
356
- | `ignore_case` | boolean | `false` | `-i` |
357
- | `count` | boolean | `false` | `-c` 只印匹配檔案數 |
358
- | `files_with_matches` | boolean | `false` | `-l` 每個匹配檔案印一個 artifact |
359
- | `once` | boolean | `false` | `--once` 第一次命中就停 |
360
- | `invert_match` | boolean | `false` | `-v` 只列沒有命中的檔案 |
361
- | `no_messages` | boolean | `false` | `-s` 靜音讀檔訊息 |
362
- | `verbose` | boolean | `false` | `--verbose` 邊分析邊回報 |
363
- | `workspace` | string | 見 admin §2.1 | — |
364
-
365
- 真實輸出(`fossil grep alpha a.txt`):
366
-
367
- ```
368
- == 2026-11-17 02:06 a.txt f3a27a552e checkin 86454b6394
369
- 1:alpha
370
- ```
371
-
372
- 空輸出 → `No matches.`
373
-
374
- ### 3.11 `fossil_whatis`
375
-
376
- ```bash
377
- fossil whatis [-f] [--type ci|t|w|g|e] [-v] <name>
378
- ```
379
-
380
- 把名字(標籤、分支、雜湊前綴、檔名)解析成 artifact。
381
-
382
- | 參數 | 類型 | 必填/預設 | 說明 |
383
- | --- | --- | --- | --- |
384
- | `name` | string | 必填 | 要解析的名字 |
385
- | `file` | boolean | `false` | `-f` 把 `name` 當檔名,查內容雜湊 |
386
- | `type` | `ci` \| `t` \| `w` \| `g` \| `e` | — | `--type` 只匹配該 artifact 類型 |
387
- | `verbose` | boolean | `false` | `-v` 附內部 record id |
388
- | `workspace` | string | 見 admin §2.1 | — |
389
-
390
- 真實輸出(`name: 'tip'`):
391
-
392
- ```
393
- name: tip
394
- artifact: 86454b6394a3b2d2e2c0e2c7a6ee2f4e0b3b5a1a5f2e0d6a0e0f0a1b2c3d4e5f
395
- size: 340 bytes
396
- tags: trunk
397
- type: Check-in by stellar on 2026-11-17 02:06:59
398
- comment: second commit
399
- ```
400
-
401
- ### 3.12 `fossil_merge_base`
330
+ ### 3.9 `fossil_merge_base`
402
331
 
403
332
  ```bash
404
333
  fossil merge-base [--ignore-merges] <v1> <v2> [...]
@@ -413,10 +342,10 @@ fossil merge-base [--ignore-merges] <v1> <v2> [...]
413
342
  真實輸出:`pivot=86454b6394a3b2d2e2c0e2c7a6ee2f4e0b3b5a1a5f2e0d6a0e0f0a1b2c3d4e5f`
414
343
  (無共同祖先時 fossil 回 `merge-base: no common ancestor` 並以非零結束)。
415
344
 
416
- ### 3.13 `fossil_leaves`
345
+ ### 3.10 `fossil_leaves`
417
346
 
418
347
  ```bash
419
- fossil leaves [-a] [-c] [-m] [--bybranch] [-W WIDTH]
348
+ fossil leaves [-a] [-c] [-m] [--recompute] [--bybranch] [-W WIDTH]
420
349
  ```
421
350
 
422
351
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -424,6 +353,7 @@ fossil leaves [-a] [-c] [-m] [--bybranch] [-W WIDTH]
424
353
  | `all` | boolean | `false` | `-a` 連已關閉的 leaf 一起列 |
425
354
  | `closed` | boolean | `false` | `-c` 只列已關閉的 leaf |
426
355
  | `multiple` | boolean | `false` | `-m` 只列有多個 leaf 的分支 |
356
+ | `recompute` | boolean | `false` | `--recompute` 重算 leaf,不讀快取 |
427
357
  | `by_branch` | boolean | `false` | `--bybranch` 按分支名排序 |
428
358
  | `width` | number | — | `-W` 輸出寬度,`0` 表示一行一筆 |
429
359
  | `workspace` | string | 見 admin §2.1 | — |
@@ -434,7 +364,7 @@ fossil leaves [-a] [-c] [-m] [--bybranch] [-W WIDTH]
434
364
  (1) 2026-11-17 02:06:59 [86454b6394] second commit (user: stellar tags: trunk)
435
365
  ```
436
366
 
437
- ### 3.14 `fossil_descendants`
367
+ ### 3.11 `fossil_descendants`
438
368
 
439
369
  ```bash
440
370
  fossil descendants [<checkin>] [-W WIDTH]
@@ -446,6 +376,7 @@ fossil descendants [<checkin>] [-W WIDTH]
446
376
  | --- | --- | --- | --- |
447
377
  | `checkin` | string | — | 起始 check-in;省略時用當前 check-out 的版本 |
448
378
  | `width` | number | — | 輸出寬度(`-W`);`0` 表示一行一筆 |
379
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
449
380
  | `workspace` | string | 見 admin §2.1 | — |
450
381
 
451
382
  真實輸出:
@@ -456,7 +387,7 @@ fossil descendants [<checkin>] [-W WIDTH]
456
387
  +++ end of timeline (1) +++
457
388
  ```
458
389
 
459
- ### 3.15 `fossil_unpublished`
390
+ ### 3.12 `fossil_unpublished`
460
391
 
461
392
  ```bash
462
393
  fossil unpublished [--all]
@@ -471,50 +402,7 @@ fossil unpublished [--all]
471
402
 
472
403
  ---
473
404
 
474
- ### 3.16 `fossil_ignore_from_gitignore`
475
-
476
- 把 `.gitignore` 的規則翻成 `ignore-glob` 認得的 glob 清單,可選擇寫成 `.fossil-settings/ignore-glob`。
477
-
478
- | 參數 | 類型 | 必填/預設 | 說明 |
479
- | --- | --- | --- | --- |
480
- | `source` | string | `.gitignore` | 要轉換的檔案,相對 workspace |
481
- | `write` | boolean | `false` | 寫入 `.fossil-settings/ignore-glob` |
482
- | `overwrite` | boolean | `false` | 覆蓋已存在的 `.fossil-settings/ignore-glob` |
483
- | `workspace` | string | 見 admin §2.1 | — |
484
-
485
- | `.gitignore` 寫法 | 產出的 glob | 原因 |
486
- | --- | --- | --- |
487
- | `# 註解`、空行 | 丟棄 | `ignore-glob` 只有樣式 |
488
- | `!name` | 略過,並在 `NOTE:` 列出 | `ignore-glob` 沒有否定 |
489
- | `name` | `name`、`*/name` | 沒有斜線的規則在 git 是任意深度,fossil 比對完整路徑 |
490
- | `*.log` | `*.log` | 開頭就是萬用字元,fossil 的 `*` 已跨目錄 |
491
- | `dir/` | `dir` | fossil 命中目錄即略過整個子樹 |
492
- | `/name` | `name` | 錨定在該 `.gitignore` 所在目錄,前綴沿用目錄名 |
493
- | `a/**/b` | `a/b`、`a/*/b` | `**` 展開成零層與多層兩條 |
494
- | 含逗號、空白、引號 | 用 `'…'` 或 `"…"` 包住 | fossil 的清單以空白與逗號分隔 |
495
-
496
- 真實輸出:
497
-
498
- ```
499
- Converted 5 rules from .gitignore into 7 ignore-glob patterns.
500
-
501
- node_modules
502
- */node_modules
503
- *.log
504
- doc/gen
505
- doc/*/gen
506
- dist
507
- */dist
508
-
509
- NOTE: `**` in doc/**/gen expanded to 2 patterns.
510
- NOTE: negation !keep.log skipped: ignore-glob has no negation, so the path stays visible.
511
- ```
512
-
513
- `write: true` 時第 2 行是 `Wrote .fossil-settings/ignore-glob.`;檔案落地後立刻生效,`fossil_extras` 不再列出被忽略的路徑。
514
-
515
- ---
516
-
517
- ### 3.17 `fossil_ls`
405
+ ### 3.13 `fossil_ls`
518
406
 
519
407
  ```bash
520
408
  fossil ls ?PATHS ...? [-r REV] [--age] [-v] [-t] [--hash]
@@ -528,6 +416,7 @@ fossil ls ?PATHS ...? [-r REV] [--age] [-v] [-t] [--hash]
528
416
  | `verbose` | boolean | `false` | 額外資訊:無 `-r` 時是變更狀態,有 `-r` 時是提交時間與大小(`-v`) |
529
417
  | `time_order` | boolean | `false` | 按時間排序(`-t`);搭配 `--age` 或 `-r` 時按提交時間 |
530
418
  | `hash` | boolean | `false` | 用雜湊而非大小+mtime 判斷檔案狀態(`--hash`),自動加上 `--verbose` |
419
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
531
420
  | `workspace` | string | 見 admin §2.1 | — |
532
421
 
533
422
  真實輸出:
@@ -540,55 +429,7 @@ $ fossil ls -r tip
540
429
  a.txt
541
430
  ```
542
431
 
543
- ### 3.18 `fossil_search`
544
-
545
- ```bash
546
- fossil search [-a] [-n N] [-W WIDTH] pattern
547
- ```
548
-
549
- | 參數 | 類型 | 必填/預設 | 說明 |
550
- | --- | --- | --- | --- |
551
- | `pattern` | string | **必填** | 要搜尋的字詞;全部都要命中 |
552
- | `all` | boolean | `false` | 輸出全部命中,而不是只給高分者(`--all`) |
553
- | `limit` | number | — | 最多輸出幾筆(`-n`) |
554
- | `width` | number | — | 輸出寬度,`0` 表示不折行(`-W`) |
555
- | `workspace` | string | 見 admin §2.1 | — |
556
-
557
- 真實輸出:
558
-
559
- ```
560
- $ fossil search second
561
- === 2026-11-17 ===
562
- 02:24:18 [5f3e19ce7a] *CURRENT* second
563
- +++ no more data (1) +++
564
- ```
565
-
566
- 沒有命中時 fossil 只印 `+++ no more data (0) +++` 並以 0 結束,工具改寫成 `No matches.`。
567
- 搜尋範圍是 timeline / event 的註解,不含檔案內容、文件或論壇文章。
568
-
569
- ### 3.19 `fossil_artifact`
570
-
571
- ```bash
572
- fossil artifact <ARTIFACT-ID>
573
- ```
574
-
575
- | 參數 | 類型 | 必填/預設 | 說明 |
576
- | --- | --- | --- | --- |
577
- | `artifact` | string | **必填** | 工件雜湊,可用唯一前綴 |
578
- | `workspace` | string | 見 admin §2.1 | — |
579
-
580
- 真實輸出(檔案版本工件):
581
-
582
- ```
583
- $ fossil artifact 17995fe087b0f2ff8b60d47f4005eb1fbab7aa3bc9e3061b09f4a446a5f5dcb8
584
- hi
585
- more
586
- ```
587
-
588
- 對 check-in 的雜湊則會印出 manifest 原文(`D`/`F`/`P`/`U` 等卡片行)。
589
- 雜湊可由 `fossil_finfo { mode: "id" }`、`fossil_whatis` 或 `fossil_leaves` 取得。
590
-
591
- ### 3.20 `fossil_describe`
432
+ ### 3.14 `fossil_describe`
592
433
 
593
434
  ```bash
594
435
  fossil describe ?VERSION? [--digits N] [--dirty] [--long] [--match GLOB]
@@ -617,7 +458,7 @@ smoke-tag-0-3c24269ef1 # <標籤>-<其後提交數>-<短雜湊>
617
458
  標籤打在祖先 check-in 上時同樣是 `<標籤>-<N>-<短雜湊>`;`match` 限制參與計算的標籤 glob
618
459
  (`match: '*'` 會把 `trunk` 這類傳播標籤也算進來)。
619
460
 
620
- ### 3.21 `fossil_archive`
461
+ ### 3.15 `fossil_archive`
621
462
 
622
463
  ```bash
623
464
  fossil tarball <version> <outfile> [-l] [--name DIR] [-X GLOBLIST] [--include GLOBLIST]
@@ -651,7 +492,7 @@ Wrote snap.zip from tip.
651
492
 
652
493
  `--name` 省略時頂層目錄名由專案名、check-in 時間與 artifact id 組成;`--include` 與 `-X` 同時命中時以排除為準。
653
494
 
654
- ### 3.22 `fossil_unversioned`
495
+ ### 3.16 `fossil_unversioned`
655
496
 
656
497
  ```bash
657
498
  fossil unversioned list|remove [--glob PATTERN] [--like PATTERN]
@@ -687,7 +528,7 @@ $ fossil unversioned cat uv-note.txt
687
528
  unversioned body
688
529
  ```
689
530
 
690
- ### 3.23 `fossil_touch`
531
+ ### 3.17 `fossil_touch`
691
532
 
692
533
  ```bash
693
534
  fossil touch [--now|-c|--checkin|-C|--checkout] [-g GLOBS] [-G] [-v] [-n] [-q] [FILES...]
@@ -707,7 +548,7 @@ fossil touch [--now|-c|--checkin|-C|--checkout] [-g GLOBS] [-G] [-v] [-n] [-q] [
707
548
  Fossil 用檔案大小與 mtime 判斷是否變更,所以在同一個時間戳內改檔案可能被忽略;`fossil_touch { mode: "now" }`
708
549
  強制重新掃描。指令本身沒有輸出。
709
550
 
710
- ### 3.24 `fossil_amend`
551
+ ### 3.18 `fossil_amend`
711
552
 
712
553
  ```bash
713
554
  fossil amend <check-in> [-n] [-m COMMENT|-M FILE] [--author USER] [--date WHEN]
@@ -746,7 +587,7 @@ T +sym-smoke-tag ead8e69115b0d294ee8168d741d226ccd54fdc5eb22ff535b6a14018c66f1a0
746
587
  U stellar
747
588
  ```
748
589
 
749
- ### 3.25 `fossil_patch`
590
+ ### 3.19 `fossil_patch`
750
591
 
751
592
  ```bash
752
593
  fossil patch create [-f] <file>
@@ -778,7 +619,7 @@ $ fossil patch diff smoke.patch
778
619
  check-out 有未提交改動時 `fossil patch apply` 會以 `there are unsaved changes in the current check-out` 失敗,
779
620
  要先 `fossil_revert` 或傳 `force: true`。
780
621
 
781
- ### 3.26 `fossil_bisect`
622
+ ### 3.20 `fossil_bisect`
782
623
 
783
624
  ```bash
784
625
  fossil bisect good|bad|skip [<version>]
@@ -812,37 +653,6 @@ $ fossil bisect chart
812
653
 
813
654
  `reset` 清掉整段 bisect 記錄,之後 `next` 才會重新從兩端算起點。
814
655
 
815
- ### 3.27 `fossil_sql`
816
-
817
- ```bash
818
- fossil sql --readonly -json "<query>"
819
- ```
820
-
821
- | 參數 | 類型 | 必填/預設 | 說明 |
822
- | --- | --- | --- | --- |
823
- | `query` | string | **必填** | 以 `SELECT` / `WITH` / `PRAGMA` / `EXPLAIN` 開頭的語句;`LIMIT` 寫在 SQL 裡 |
824
- | `repository` | string | check-out 的倉庫 | 直接指定倉庫檔(`-R`),可在沒有 check-out 的目錄查詢 |
825
- | `workspace` | string | 見 admin §2.1 | — |
826
-
827
- 輸出是製表符分隔的表格,最後一行是 `N row(s).`;空結果印 `No rows.`。查詢以 `--readonly` 開啟,
828
- `fossil sql` 的錯誤(例如 `no such column: name`)由工具轉成 `isError`。
829
-
830
- 真實輸出:
831
-
832
- ```
833
- $ fossil sql --readonly -json "SELECT count(*) AS n FROM event"
834
- n
835
- 2
836
-
837
- 1 row(s).
838
- ```
839
-
840
- 以 `DELETE` / `UPDATE` 開頭的語句在交給 fossil 前就被拒絕:
841
-
842
- ```
843
- ERROR: the query must start with SELECT, WITH, PRAGMA or EXPLAIN.
844
- ```
845
-
846
656
  ## 4. 暫存與提交
847
657
 
848
658
  ### 4.1 `fossil_add`
@@ -931,8 +741,10 @@ fossil addremove --reset [-n] [-v] # reset: true
931
741
  ### 4.5 `fossil_commit`
932
742
 
933
743
  ```bash
934
- fossil commit -m <message> [--branch B] [--no-warnings] [--allow-empty] [--close]
935
- [--bgcolor COLOR] [--date-override DATE] [--tag TAG ...] [--user-override U] [files...]
744
+ fossil commit -m <message> [-M FILE] [--mimetype TYPE] [--branch B] [--no-warnings]
745
+ [--allow-empty] [--allow-fork] [--allow-conflict] [--allow-older] [--integrate]
746
+ [--private] [--hash] [--no-verify] [--dry-run] [--close] [--bgcolor COLOR]
747
+ [--date-override DATE] [--tag TAG ...] [--user-override U] [files...]
936
748
  # stdin = "y\na\n"
937
749
  ```
938
750
 
@@ -943,6 +755,16 @@ fossil commit -m <message> [--branch B] [--no-warnings] [--allow-empty] [--close
943
755
  | `branch` | string | — | `--branch` 把新 check-in 放到指定分支 |
944
756
  | `no_warnings` | boolean | `false` | `--no-warnings` |
945
757
  | `allow_empty` | boolean | `false` | `--allow-empty`(無檔案變更也能提交) |
758
+ | `allow_fork` | boolean | `false` | `--allow-fork` 允許這次提交在分支上分叉 |
759
+ | `allow_conflict` | boolean | `false` | `--allow-conflict` 帶著未解決的合併衝突提交 |
760
+ | `allow_older` | boolean | `false` | `--allow-older` 允許比祖先更舊的時間戳記 |
761
+ | `integrate` | boolean | `false` | `--integrate` 關閉所有已併入本分支的分支 |
762
+ | `private_checkin` | boolean | `false` | `--private` 這個 check-in 不隨 push 出去 |
763
+ | `hash` | boolean | `false` | `--hash` 用雜湊而非大小+mtime 判斷檔案變更 |
764
+ | `no_verify` | boolean | `false` | `--no-verify` 跳過提交前的 hook |
765
+ | `dry_run` | boolean | `false` | `--dry-run` 只顯示會提交什麼 |
766
+ | `message_file` | string | — | `-M` 從檔案讀提交訊息,優先於 `message` |
767
+ | `mimetype` | string | — | `--mimetype` 提交訊息的 mimetype |
946
768
  | `close` | boolean | `false` | `--close` 提交後關閉所在分支 |
947
769
  | `bgcolor` | string | — | `--bgcolor` 只套用在這一個 check-in 的背景色 |
948
770
  | `date_override` | string | — | `--date-override` 指定提交時間(如 `2026-11-17 12:00:00`) |
@@ -970,7 +792,8 @@ fossil revert [-r REV] [files...]
970
792
  ### 4.7 `fossil_clean`
971
793
 
972
794
  ```bash
973
- fossil clean [--dotfiles] [--ignore GLOBS] [--clean CSG] [-x] [--temp] [--dirsonly] [--emptydirs] [-v] [-n]
795
+ fossil clean [--dotfiles] [--ignore GLOBS] [--clean CSG] [--keep GLOBS] [-x] [--temp]
796
+ [--dirsonly] [--emptydirs] [--disable-undo] [--allckouts] [-i] [--case-sensitive 1|0] [-v] [-n]
974
797
  fossil clean -f # all_files: true
975
798
  fossil clean --no-prompt # 都不給(預設)
976
799
  ```
@@ -986,6 +809,11 @@ fossil clean --no-prompt # 都不給(預設)
986
809
  | `temp` | boolean | `false` | 連暫存檔一起清(`--temp`) |
987
810
  | `dirs_only` | boolean | `false` | 只刪空目錄(`--dirsonly`) |
988
811
  | `empty_dirs` | boolean | `false` | 一併刪除空目錄(`--emptydirs`) |
812
+ | `keep` | string | — | `--keep` 的 CSG,符合的未管理檔案永不刪除 |
813
+ | `disable_undo` | boolean | `false` | `--disable-undo` 不留 undo 備份 |
814
+ | `all_checkouts` | boolean | `false` | `--allckouts` 連巢狀 check-out 的空目錄一起掃 |
815
+ | `prompt` | boolean | `false` | `-i` 每個檔案都問(等於關閉 undo 備份) |
816
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
989
817
  | `verbose` | boolean | `false` | 逐檔回報(`-v`) |
990
818
  | `workspace` | string | 見 admin §2.1 | — |
991
819
 
@@ -1097,7 +925,7 @@ fossil merge [-n] [--integrate] [--cherrypick|--backout] [--baseline V] [--binar
1097
925
  ### 5.4 `fossil_update`
1098
926
 
1099
927
  ```bash
1100
- fossil update [--latest] [--nosync] [--setmtime] [--force-missing] [-K] [-v] [target]
928
+ fossil update [--latest] [--nosync] [--setmtime] [--force-missing] [--case-sensitive 1|0] [-K] [-W N] [-v] [target]
1101
929
  fossil update -n [target] # dry_run: true
1102
930
  ```
1103
931
 
@@ -1110,6 +938,8 @@ fossil update -n [target] # dry_run: true
1110
938
  | `set_mtime` | boolean | `false` | `--setmtime` 把檔案時間戳設成最後一次相關提交的時間 |
1111
939
  | `keep_merge_files` | boolean | `false` | `-K` 衝突時保留 `*-baseline` / `*-original` / `*-merge` |
1112
940
  | `force_missing` | boolean | `false` | `--force-missing` 即使有一側內容缺失也更新 |
941
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
942
+ | `width` | number | — | `-W` 輸出寬度 |
1113
943
  | `verbose` | boolean | `false` | `-v` 列出每個檔案的處理結果 |
1114
944
  | `workspace` | string | 見 admin §2.1 | check-out 目錄 |
1115
945
 
@@ -1151,7 +981,7 @@ fossil_timeline { limit: 5 }
1151
981
 
1152
982
  ## 7. 已知邊界
1153
983
 
1154
- 1. **`fossil_status` 的未跟蹤檔案來自第二條命令**(`fossil extra`),兩者併發執行。單條失敗時該段渲染成
984
+ 1. **`fossil_status` 的未跟蹤檔案來自第二條命令**(`fossil extra`)。單條失敗時該段渲染成
1155
985
  `--- STATUS ---` + `ERROR: …`,但 `isError` 只為 `true` 當**兩段都失敗**(`renderSections` 的規則)。
1156
986
  2. **`commit` 自動回答兩個互動提示**:未知檔名參數的 `continue (y/N)?` 答 `y`,內容警告的
1157
987
  `Commit anyhow (a=all/y/N)?` 答 `a`(all);二進位制檔案與忽略規則的衝突一律照交。
@@ -1161,11 +991,8 @@ fossil_timeline { limit: 5 }
1161
991
  5. **`tag cancel` / `branch new` 的預設值**(`tip` / `current`)是工具補的,不是 fossil 原生預設。
1162
992
  6. **版本表示式**只支援 fossil 自身語法(`tip`、雜湊前綴、`branch:name` 等);`tip-1` 這類寫法會失敗。
1163
993
  7. **路徑原樣傳遞**:以 `-` 開頭的檔名需要 `./` 前綴。
1164
- 8. **除 `fossil_sql` 可用 `repository` 直接查詢外,工具都要求已 open 的 check-out**;只有倉庫檔案(.fossil)時用 admin 的 `fossil_open`。
1165
- 9. **`fossil_ignore_from_gitignore` 沿用 fossil 的深度語意**:git 的 `*` 不跨 `/`,fossil 的跨,所以含斜線的樣式
1166
- (`src/*.o`)在 fossil 會連更深的路徑一起匹配。
1167
- 10. **`ignore-glob` 沒有否定**:`!` 開頭的行只能略過並在 `NOTE:` 說明,被 git 重新納入的檔案在 fossil 仍被忽略。
1168
- 11. **`fossil_mv` 的 `--hard`**:目標位置已有未管理的同名檔案時,該檔案被覆寫;來源在先前
994
+ 8. **帶 `repository` 的工具讀倉庫檔,其餘要求已 open 的 check-out**;只有倉庫檔案(.fossil)時用 admin 的 `fossil_open`。
995
+ 9. **`fossil_mv` 的 `--hard`**:目標位置已有未管理的同名檔案時,該檔案被覆寫;來源在先前
1169
996
  `hard: false` 只記錄 RENAME 後已不在磁碟上,`--hard` 會以 `cannot open "…" for reading` 失敗,
1170
997
  但 RENAME 事件已寫入。
1171
998
 
@@ -1175,8 +1002,8 @@ fossil_timeline { limit: 5 }
1175
1002
 
1176
1003
  | 檔案 | 內容 |
1177
1004
  | --- | --- |
1178
- | `src/tools/version-control.ts` | 40 個工具的註冊、參數 schema、argv 拼裝、`renderSections` 分節輸出 |
1005
+ | `src/tools/version-control.ts` | 33 個工具的註冊、參數 schema、argv 拼裝、`renderSections` 分節輸出 |
1179
1006
  | `src/tools/common.ts` | `workspaceParam`、`flag()`、`clean()`、`pushOption()` 等共享片段 |
1180
1007
  | `src/core/fossil.ts` | `runFossil`(spawn + 超時 + 輸出截斷)、`renderOutcome`、`formatFailure` |
1181
1008
  | `src/config.ts` | `FOSSIL_BIN`、`FOSSIL_TIMEOUT_MS`、`FOSSIL_MAX_CAPTURE_BYTES` 等 |
1182
- | `src/capabilities.ts` | 能力註冊表(`v` → 本檔案 40 個工具) |
1009
+ | `src/capabilities.ts` | 能力註冊表(`v` → 本檔案 33 個工具) |
package/docs/wiki.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Wiki 能力(`-c w`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.2.0` 及之後,fossil 2.21 實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.2` 及之後,fossil 2.21 實測。
4
4
 
5
5
  `-c w` 註冊 3 個工具:`fossil_wiki_ls` / `fossil_wiki_read` / `fossil_wiki_write`。
6
6
  (組合啟用:`-c aw`。)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@stellar_ai/mcp_fossil_scm",
3
- "version": "0.2.0",
4
- "description": "Capability-scoped MCP server for Fossil SCM: Admin, VCS, Forum, Tickets, Wiki and Chat",
3
+ "version": "0.2.2",
4
+ "description": "Capability-scoped MCP server for Fossil SCM: Admin, Utils, VCS, Tickets, Chat, Forum and Wiki",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "bin": {
@@ -42,10 +42,12 @@
42
42
  "start": "node dist/index.js",
43
43
  "dev": "pnpm build && node dist/index.js --verbose",
44
44
  "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
45
+ "make:testbed": "node scripts/make-testbed.mjs",
45
46
  "prebuild": "pnpm clean",
46
47
  "smoke": "node scripts/smoke.mjs",
47
48
  "test": "pnpm typecheck && pnpm build && pnpm check:docs && pnpm smoke",
48
49
  "link-local": "bash scripts/link-local.sh",
49
- "check:docs": "node scripts/check-docs.mjs"
50
+ "check:docs": "node scripts/check-docs.mjs",
51
+ "pretest": "pnpm make:testbed"
50
52
  }
51
53
  }