Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern

[kiki830621]

Problem

Issue #7 抽 parseGetChatHistoryArgs pure function 重構了 get_chat_history handler，但 dump_chat_to_markdown handler (Server.swift:466-499) 保留同樣的 inline 驗證邏輯：

• chat_id guard
• max_messages 0/10_000 cap (一字不差)
• parseISODate + parseUntilDate with DateParseError catch
• errorResult 轉換

From verification of #7 by devils-advocate (HIGH):
「若未來改 HandlerArgs.swift 的 cap policy，dump_chat_to_markdown 會 silently drift。commit message 和 code comment 都沒提這 exception，test file 名稱 ServerHandlerLogicTests 又泛化，下個 reviewer 容易誤以為『all handlers covered』」

Type

refactor

Expected

• 抽 DumpChatToMarkdownArgs struct + parseDumpChatToMarkdownArgs(_ args:) throws -> ... pure function
• 或 generalize: parseGetChatHistoryArgs → parseChatHistoryArgs（帶 isDumpMode: Bool 或 output context），兩個 handler 共用
• 對應 unit tests 覆蓋 dump_chat_to_markdown 的 validation 路徑

Code Reference

• Sources/CheTelegramAllMCPCore/Server.swift:466-499（被忽略的 handler）
• Sources/CheTelegramAllMCPCore/HandlerArgs.swift（可 extend 的模組）

Related: #7

---

Current Status

Phase: closed
Last updated: 2026-04-26 by idd-close

Key Decisions

• 採 Option A（parallel struct + parser）拒絕 Option B（god function with isDumpMode）
• 額外抽 validateMaxMessagesCap shared helper：兩個 parser 共用 0/10_000 cap invariant
• Two-phase commit strategy：Phase 1 prerequisite extract、Phase 2 dump parser + tests
• Direct-commit path（一致於 get_chat_history: from_message_id=0 首次呼叫只回傳 1 則訊息 #3-MCP 層補 handler 行為 unit test（get_chat_history） #7、Test hardening: int64 helper DRY + boundary + TZ assertions #15）
• 6-AI verify: 5 PASS + 1 in-scope DA fix（CHANGELOG 10 → 11）+ 4 follow-ups + 2 won't-fix（理由透明）

Scope Changes

• 增補：testDumpExplicitSelfLabel（scope+1，default vs explicit override 對稱覆蓋，已透明標註）
• 增補：CHANGELOG 10 new tests → 11 new tests in-scope fix（commit ac306ba）

Blocking

(none)

Follow-up

• Catch chain integration tests for handler error wiring (#7/#13 follow-up) #18 — Catch chain integration tests for handler error wiring（DA MEDIUM）
• TZ symmetric mutation guard for testUntilDateUsesEndOfDay (parity with #16) #19 — TZ symmetric mutation guard parity（fold into Test design: fixed-TZ assertion to catch symmetric TZ mutations #16 family）
• max_messages silently falls back to default for .string/.double values (cap bypass) #20 — max_messages .string/.double silently bypass cap（pre-existing parity bug）
• output_path traversal hardening for dump_chat_to_markdown #21 — output_path traversal hardening（pre-existing security MEDIUM）

Test counts

• 139 → 150 (+11), 0 failures
• Codex 獨立驗證 24 tests pass

Commits

• a834e88 refactor: extract validateMaxMessagesCap shared helper (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13)
• f4ea946 refactor: extract parseDumpChatToMarkdownArgs pure function (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13)
• ac306ba docs: fix CHANGELOG test count 10 → 11 (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13)

[kiki830621]

Diagnosis

Type

refactor + test enhancement

Analysis

兩個 handler validation 對比：

Rule	get_chat_history	dump_chat_to_markdown
chat_id required	✓	✓
output_path required	—	✓ (unique)
max_messages 0 lower bound	✓	✓
max_messages 10_000 cap	✓	✓（一字不差 duplicate）
max_messages default	nil（#3 auto-pagination 補 limit）	5000
since_date / until_date parse	✓	✓
self_label default	—	"我"
limit default 50	✓	—
from_message_id default 0 + #3 auto-pagination	✓	—

3 個共同 rule, 3 個獨有 rule。Server.swift:516-524 的 cap validation 與 HandlerArgs.swift:48-56 一字不差。

Strategy

採 Option A（issue body 列的兩選項中的第一個）+ 抽 shared cap validator：

1. 抽 validateMaxMessagesCap(_ value: Int) throws 模組級 helper（共同 invariant 單點維護）
2. 重構 parseGetChatHistoryArgs 改用 validateMaxMessagesCap
3. 新增 DumpChatToMarkdownArgs struct + parseDumpChatToMarkdownArgs(_ args:) throws pure function
4. Server.swift handler 改用 pure function
5. 測試覆蓋

為何不採 Option B（god function with isDumpMode: Bool）：分支邏輯藏進函式、模糊兩個 handler 的契約差異、名字曖昧。Option A 維持每個 handler args struct 自我描述。

Complexity

Simple — 無新抽象、無架構決策；純 extract pattern。

Risks

• parseGetChatHistoryArgs 既有 7 個 boundary tests 不能 regress
• dumpChatToMarkdown 的 default 值（max_messages=5000、self_label="我"）必須保留行為等價

---

Implementation Plan

Direct-commit path（一致於 #3-#7、#15）。

Phase 1: Extract shared cap validator

• HandlerArgs.swift 新增 validateMaxMessagesCap(_ value: Int) throws
• parseGetChatHistoryArgs 重構改呼叫 validateMaxMessagesCap
• 跑 swift test --skip E2ETests，139 既有 tests 全綠（regression guard）

Phase 2: Add parseDumpChatToMarkdownArgs

• HandlerArgs.swift 新增 DumpChatToMarkdownArgs struct（chatId / outputPath / maxMessages / sinceDate / untilDate / selfLabel）
• HandlerArgs.swift 新增 parseDumpChatToMarkdownArgs(_ args:) throws -> DumpChatToMarkdownArgs
• Server.swift 的 dump_chat_to_markdown case 改呼叫 pure function（替代 inline 驗證 lines 510-532）

Phase 3: Test coverage

• testDumpRequiresChatId — chat_id 缺失 throws
• testDumpRequiresOutputPath — output_path 缺失 throws
• testDumpDefaultMaxMessagesIs5000 — 沒傳 max_messages 時為 5000
• testDumpDefaultSelfLabel — 沒傳 self_label 時為「我」
• testDumpMaxMessagesAt10001Rejected — boundary parity（Test hardening: int64 helper DRY + boundary + TZ assertions #15-C2）
• testDumpMaxMessagesAt10000Accepted — boundary parity
• testDumpMaxMessagesAt9999Accepted — symmetric downward parity（Test hardening: int64 helper DRY + boundary + TZ assertions #15 DA finding）
• testDumpMaxMessagesRejectsZeroOrNegative
• testDumpInvalidDateThrows
• testDumpUntilDateUsesEndOfDay — 含 year/month/day assertions（Test hardening: int64 helper DRY + boundary + TZ assertions #15-C3 parity）

Phase 4: Verify + CHANGELOG

• swift build pass
• swift test --skip E2ETests: 149 tests pass (139 + 10 new)
• CHANGELOG.md [0.5.2] Refactored + Test sections

Commit strategy

拆 2 atomic commits：

1. Extract shared cap validator + parseGetChatHistoryArgs refactor（Phase 1）
2. Add parseDumpChatToMarkdownArgs + Server.swift handler + tests（Phase 2-3）

CHANGELOG 進 commit 2 一起。

Documentation

• CHANGELOG entry

Scope check

✅ 全部追溯 #13 的 Expected。Phase 1 是 prerequisite refactor，Phase 2-3 是核心改動，Phase 4 是收尾。

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

Phase 1: Extract shared cap validator

• HandlerArgs.swift 新增 validateMaxMessagesCap(_ value: Int) throws
• parseGetChatHistoryArgs 重構改呼叫 validateMaxMessagesCap
• swift test --skip E2ETests: 139 既有 tests 全綠（regression guard）

Phase 2: Add parseDumpChatToMarkdownArgs

• HandlerArgs.swift 新增 DumpChatToMarkdownArgs struct（chatId / outputPath / maxMessages / sinceDate / untilDate / selfLabel）
• HandlerArgs.swift 新增 parseDumpChatToMarkdownArgs(_ args:) throws
• Server.swift dump_chat_to_markdown case 改呼叫 pure function（lines 510-532 → 15 行 parse-then-call）

Phase 3: Test coverage

• testDumpRequiresChatId
• testDumpRequiresOutputPath
• testDumpDefaultMaxMessagesIs5000
• testDumpDefaultSelfLabel
• testDumpExplicitSelfLabel — scope+1：default vs explicit override 對稱覆蓋（同 parser 內緊密測試，透明標註）
• testDumpMaxMessagesAt10001Rejected — boundary parity（Test hardening: int64 helper DRY + boundary + TZ assertions #15-C2）
• testDumpMaxMessagesAt10000Accepted — boundary parity
• testDumpMaxMessagesAt9999Accepted — symmetric downward parity（Test hardening: int64 helper DRY + boundary + TZ assertions #15 DA finding）
• testDumpMaxMessagesRejectsZeroOrNegative
• testDumpInvalidDateThrows
• testDumpUntilDateUsesEndOfDay — 含 year/month/day assertions（Test hardening: int64 helper DRY + boundary + TZ assertions #15-C3 parity）

Phase 4: Verify + CHANGELOG

• swift build pass
• swift test --skip E2ETests: 150 tests pass（139 + 11 new；plan 寫 10，實際 11）
• CHANGELOG.md [0.5.2] Refactored + Test sections

Legend: - [x] done · - [~] skipped (may revisit) · - [-] won't fix (scope)
idd-close will refuse to close if any - [ ] remains in this checklist.

Changes

• a834e88 refactor: extract validateMaxMessagesCap shared helper (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13)
• f4ea946 refactor: extract parseDumpChatToMarkdownArgs pure function (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13)

Files Changed

 CHANGELOG.md                                       |  12 +++
 HandlerArgs.swift                                  |  75 ++++++++++++--
 Server.swift                                       |  36 ++-----
 ServerHandlerLogicTests.swift                      | 114 +++++++++++++++++++++
 4 files changed, 203 insertions(+), 34 deletions(-)

Test counts

• Before: 139 tests
• After: 150 tests (+11)
• All pass

Scope Compliance

所有改動可追溯 #13 的 Expected。1 個 transparent scope+1：plan 寫 10 個 dump tests 但實際加 11 個（多了 testDumpExplicitSelfLabel 對稱覆蓋 default→override path）。同 parser 內緊密測試，無 cross-cutting effect。

Architectural notes

• 採 issue body 列的 Option A（parallel struct + parser）而非 Option B（god function with isDumpMode: Bool）— 維持每個 handler args struct 自我描述。
• 額外抽出 validateMaxMessagesCap shared helper：兩個 parser 對 0/10_000 cap 共用 invariant，未來改 cap policy（free vs paid tier）只改一處。

Next: verification pending

[kiki830621]

Verify: #13

Engine

Agent Team (5 Claude reviewers: requirements / logic / security / regression / devils-advocate) + Codex (gpt-5.5 xhigh)

要求覆蓋率

3/3 sub-requirements addressed：

• Req 1（DumpChatToMarkdownArgs struct + parseDumpChatToMarkdownArgs pure function）：FULLY
• Req 2（generalize parseGetChatHistoryArgs with isDumpMode flag）：N/A — issue body 列為 alternative，作者選 Option A
• Req 3（unit tests covering validation paths）：FULLY（pure function 11 tests），DA 嚴格解讀為 PARTIAL（缺 handler wiring layer，見 finding feat(all-mcp): 支援一次抓取完整對話歷史（自動分頁） #1 follow-up）

Findings（合併去重，按 severity 排序）

#	Severity	Finding	Source	Action
1	—	Behavior 100% equivalent — 6-input truth table byte-level match（chat_id 缺 / output_path 缺 / default 5000 / =0 throw / =10001 throw / self_label "我"），驗證順序 chat_id→output_path→cap→since→until→self_label 完全一致	team:logic + codex	PASS
2	—	21 callers untouched, int64ArrayArg 未誤改, MarkdownExporter signature 未變, CLI 未受影響	team:regression + codex	PASS
3	—	139 → 150 tests pass, 0 regression（既有 8 個 parseGetChatHistory tests 仍綠）	team:regression + codex	PASS
4	—	Visibility private → internal 不擴大攻擊面（純 parse function、無 side effect、僅同 module 可見）	team:security	PASS
5	—	validateMaxMessagesCap shared helper 是 security-positive（消除 #7 silent drift）	team:security	PASS
6	MEDIUM	Server.swift handler catch chain（HandlerArgError vs DateParseError 兩層 catch）沒有任何 integration test 覆蓋。pure function 路徑全 cover，wiring 層 0 cover——若未來改 thrown error type 會 silently 走進 generic catch	team:devils-advocate	Follow-up
7	LOW	testDumpUntilDateUsesEndOfDay 繼承 #15-C3 的 TZ symmetric mutation gap（Calendar.current round-trip 對稱對 timezone-mapping mutation 無感）	team:devils-advocate	Follow-up（fold into #16）
8	LOW	Phase 1 commit a834e88 是 dirty checkpoint — 抽 helper 但 dump 仍 inline；git bisect 落到此 commit 會看到 transient duplication	team:devils-advocate	Won't fix（已過 bisect window，無未來風險）
9	LOW	args["max_messages"]?.intValue 嚴格 case match — .string("5000") / .double(5000.0) / .double(20000.0) 全部回 nil → silently fallback to 5000，繞過 cap 檢查。pre-existing parity for both parsers	team:devils-advocate	Follow-up（pre-existing latent bug）
10	LOW	output_path 無路徑驗證（traversal / arbitrary write）— pre-existing, 非 regression	team:security	Follow-up（已建議獨立 hardening issue）
11	INFO	testDumpExplicitSelfLabel 是 scope+1 dressed up — self_label 沒 throw 條件不算 validation path	team:devils-advocate	Won't fix（透明標註 + 對稱 default/override 覆蓋有用）
12	INFO	CHANGELOG 10 new tests vs 實際 11 — commit message 寫 11，CHANGELOG 寫 10，scope+1 化石證據	team:devils-advocate + regression	In-scope fix ✓ commit ac306ba

Devil's Advocate 反駁有效率

6 條 findings，3 個 follow-up（#6/#7/#9，皆 valid）、1 個 in-scope fix 已修（#12）、2 個 won't fix（#8/#11，理由透明）。Codex 也獨立確認 PASS（自跑 swift test --filter ServerHandlerLogicTests = 24 tests pass）。

Scope Check

PASS — 改動限於 4 檔案（HandlerArgs / Server / ServerHandlerLogicTests / CHANGELOG），全部追溯 #13 的 Expected。parseGetChatHistoryArgs 內部修改是合理的 prerequisite extraction（commit a834e88）。

Tests

• 139 → 150 tests pass, 0 failures
• Codex 獨立驗證（swift test --filter ServerHandlerLogicTests）= 24 tests pass

Commits

• a834e88 refactor: extract validateMaxMessagesCap shared helper (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13)
• f4ea946 refactor: extract parseDumpChatToMarkdownArgs pure function (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13)
• ac306ba docs: fix CHANGELOG test count 10 → 11 (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13) — DA in-scope fix

判決

PASS — 無 blocking findings；1 個 INFO 已 in-scope 修復（ac306ba）；3 個 valid follow-ups 待 user triage（#6 catch chain integration tests、#7 TZ symmetric mutation guard、#9 silent fallback hidden behavior bypass cap）。

[kiki830621]

Closing Summary

Problem

#7 verify 階段 Devil's Advocate（HIGH）發現：抽 parseGetChatHistoryArgs pure function 重構 get_chat_history 時，dump_chat_to_markdown handler (Server.swift:466-499) 仍保留同樣的 inline 驗證邏輯——chat_id guard、max_messages 0/10_000 cap（一字不差）、parseISODate/parseUntilDate with DateParseError catch。任何後續對 cap policy 的改動都會 silently drift（commit message 和 code comment 都沒提這 exception，test file 名稱 ServerHandlerLogicTests 又泛化，讓下個 reviewer 容易誤以為 all handlers covered）。

Root Cause

• 歷史脈絡：MCP 層補 handler 行為 unit test（get_chat_history） #7 PR 抽 pure function 時 scope 守在 get_chat_history 一個 handler，故意不把 dump_chat_to_markdown 也納入（避免 scope creep）。但這留下的 silent drift 風險被 MCP 層補 handler 行為 unit test（get_chat_history） #7 verify Devil's Advocate 紀錄成 follow-up，後來具現為 Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13。
• 重複的本質：兩個 handler 共用三類 invariant（chat_id 必須、0/10_000 cap、ISO date parsing），但歷史上沒有 shared infrastructure。HandlerArgs.swift 在 MCP 層補 handler 行為 unit test（get_chat_history） #7 之後成為「pure parsing/validation 模組」，Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13 自然延伸這個位置。

Solution

採 issue body 列的 Option A（parallel struct + parser），拒絕 Option B（god function with isDumpMode: Bool）—— 維持每個 handler args struct 自我描述。

Phase 1（commit a834e88）：抽 validateMaxMessagesCap(_ value: Int) throws 共用 helper，parseGetChatHistoryArgs 改呼叫。139 既有 tests 全綠（行為等價 guard）。

Phase 2（commit f4ea946）：

• 新增 DumpChatToMarkdownArgs struct（chatId / outputPath / maxMessages / sinceDate / untilDate / selfLabel）+ parseDumpChatToMarkdownArgs(_ args:) throws pure function
• Server.swift 的 dump_chat_to_markdown case 改呼叫 pure function（27 行 inline → 15 行 parse-then-call）
• 11 個新 tests 覆蓋：required fields、defaults (5000/我)、boundary parity with Test hardening: int64 helper DRY + boundary + TZ assertions #15-C2/C3（10001/10000/9999 三點 + year/month/day TZ assertions）、zero/negative rejection、invalid date

Phase 3（commit ac306ba，DA in-scope fix）：CHANGELOG 10 new tests → 11 new tests（commit message 早就寫 11，CHANGELOG 漏改）。

關鍵設計：抽 validateMaxMessagesCap shared helper 是 security-positive 改動——未來改 cap policy（free vs paid tier）會 atomically 影響兩個 handler；boundary tests 也對稱鎖在兩邊（10001/10000/9999 三點），完整 mutation guard。

Verification

Engine：5 Claude reviewers（requirements / logic / security / regression / devils-advocate）+ Codex (gpt-5.5 xhigh) = 6-AI review。

維度	Result
3/3 sub-requirements addressed（Req 2 alternative not chosen by design）	PASS
6-input behavior truth table byte-level match	PASS（logic + codex 雙向驗證）
驗證順序一致（chat_id→output_path→cap→since→until→self_label）	PASS（logic）
21 callers untouched, MarkdownExporter signature 未變, CLI 不受影響	PASS（regression + codex）
Tests 139 → 150 (+11), 0 regression	PASS（codex 獨立跑 swift test 確認）
Visibility private→internal 不擴大攻擊面	PASS（security）
Shared validateMaxMessagesCap 為 security-positive	PASS（security）

DA 找出 6 valid observations：1 in-scope fix（ac306ba，CHANGELOG 對齊）、3 valid follow-ups（已開 #18/#19/#20）、1 pre-existing security 也開 follow-up（#21）、2 won't fix（理由透明：dirty checkpoint 已過 bisect window，scope+1 透明標註）。

Changes

• a834e88 refactor: extract validateMaxMessagesCap shared helper (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13)
• f4ea946 refactor: extract parseDumpChatToMarkdownArgs pure function (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13)
• ac306ba docs: fix CHANGELOG test count 10 → 11 (Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13)

Follow-up

• Catch chain integration tests for handler error wiring (#7/#13 follow-up) #18 — Catch chain integration tests for handler error wiring（DA MEDIUM，handler wiring 0 cover）
• TZ symmetric mutation guard for testUntilDateUsesEndOfDay (parity with #16) #19 — TZ symmetric mutation guard parity for testDumpUntilDateUsesEndOfDay（DA LOW，與 Test design: fixed-TZ assertion to catch symmetric TZ mutations #16 同族）
• max_messages silently falls back to default for .string/.double values (cap bypass) #20 — max_messages .string/.double silently bypass cap（DA LOW，pre-existing latent bug 影響兩個 parser）
• output_path traversal hardening for dump_chat_to_markdown #21 — output_path traversal hardening（security MEDIUM，pre-existing）