superpowers-mcp 6.0.0 → 6.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md)
 
-[![Version](https://img.shields.io/badge/version-6.0.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.0.2-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 This document summarizes the information and usage instructions for packaging the original Superpowers skills library into an independent MCP Toolpack.
@@ -128,7 +128,38 @@ These skills are designed for orchestrating complex meta-execution patterns with
 
 ## 🆕 Recent Updates
 
-### v6.0.0 (Latest)
+### v6.0.2 (Latest)
+- **Modular Refactoring & Performance Upgrades**:
+  - **Decoupled Architecture**: Extracted file system access, metadata caching, and parsing logic into a dedicated [`src/skills-manager.ts`](src/skills-manager.ts), leaving [`src/server.ts`](src/server.ts) purely focused on MCP protocol handling.
+  - **O(1) Map-Based Cache**: Replaced the $O(N)$ double-array scan with case-insensitive, dual-key (by name and directory name) memory caches for fast $O(1)$ lookups.
+  - **Async I/O Pipeline**: Swapped synchronous file API calls (`readdirSync`, `readFileSync`) with promises and `Promise.all` concurrent execution, unlocking high-throughput performance.
+  - **Markdown Cache**: Cached stripped skill content in memory to avoid repetitive disk reads when tools are invoked frequently.
+- **Security Hardening**:
+  - **ReDoS Prevention**: Replaced regex-based frontmatter parser with a safe, line-by-line state machine parser, completely eliminating CPU exhaustion risks and supporting multiline YAML descriptions.
+  - **Path Traversal Shield**: Added strict alphanumeric white-listing (`/^[a-zA-Z0-9-_]+$/`) on skill name inputs to prevent traversal attacks.
+  - **Directory Injection Check**: Validated `SKILLS_PATH` to actively reject potentially hostile system root folders.
+  - **Path & Username Leak Protection**: Caught native file system errors and masked them into generic, path-free `McpError` payloads.
+  - **Windows Build and Script Safety**: Handled Windows `chmodSync` platform checks in `esbuild.js` and skipped Symlinks in `copy-skills.js` to prevent recursive file copy loops.
+
+- **Upstream Security Cherry-Picks**: Applied security hardening from obra/superpowers v6.1.1:
+  - **WebSocket frame size validation**: Added `MAX_FRAME_PAYLOAD_BYTES (10 MB)` check in `decodeFrame()` to prevent oversized frame attacks (CWE-789). Dual protection — BigInt extended-length and general post-resolution guard.
+  - **Hardlink containment**: Added `stat.nlink !== 1` check in `isRegularFileInsideContentDir()` prevents path traversal via hardlinks.
+  - **`escapeHtmlText()` extraction**: Extracted inline `escHtml` closure into a reusable named function for consistent HTML escaping.
+  - **URL parsing refactor**: Extracted `pathnameOf()` and `queryKey()` helpers, reducing duplicate inline URL logic in `handleRequest()`.
+- **`review-package` Path Resolution Fix**: Fixed `sdd-workspace` invocation to use absolute path resolution (`$(cd "$(dirname "$0")" && pwd)`) instead of relative path, fixing CWD-dependent failures.
+- **Windows Native Helper Scripts**: Added PowerShell wrappers for Visual Companion startup/shutdown, SDD review/task helpers, and systematic-debugging polluter detection.
+- **Skill Documentation Enhancements**:
+  - `subagent-driven-development`: Added `plan-mandated` review guidance for handling plan conflicts.
+  - `writing-skills`: Strengthened prohibition vs. recipe guidance with empirical evidence from wording tests.
+  - `test-driven-development`: Fixed table formatting for clarity.
+  - `writing-skills/anthropic-best-practices`: Updated image CDN URLs.
+- **`helper.js` Comment Alignment**: Added 4 clarifying inline comments to align with upstream documentation without changing behavior. DOM-safe `showTombstone()` preserved (no `innerHTML` regression).
+- **Cleanup**: Removed obsolete `walkthrough.md` (v5.1.0 upgrade guide).
+
+### v6.0.1
+- **Security Fix — Reflected XSS (#2)**: Fixed server-side reflected cross-site scripting in `skills/brainstorming/scripts/server.cjs`. The `bootstrapPage()` function was called with the user-supplied `keyFromQuery` parameter (even though validated via `timingSafeEqualStr`). Changed to use the server-side `TOKEN` constant instead, eliminating user-tainted data from the HTML response sink. Zero behavior change (the validated value is identical).
+
+### v6.0.0
 - **Upstream Sync with obra/superpowers v6.1.1**: Major synchronization bringing upstream improvements across all skills.
 - **subagent-driven-development Redesign**: Consolidated two-stage review (spec → code quality) into a single "task reviewer" sub-agent, plus added a broad **whole-branch final review** at completion. New **Pre-Flight Plan Review** catches task conflicts before execution begins. Added **Model Selection Guidance** to optimize cost vs. turn count.
 - **using-superpowers Simplified**: Removed platform-specific sections and Graphviz diagram. Introduced **per-platform reference files** (`antigravity-tools.md`, `pi-tools.md`) and updated `codex-tools.md` for cleaner multi-environment support.

package/README.zh-TW.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md)
 
-[![版本](https://img.shields.io/badge/version-6.0.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![版本](https://img.shields.io/badge/version-6.0.2-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![授權](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 本文檔總結了將原始 Superpowers 技能庫打包成獨立 MCP Toolpack 的相關資訊與使用說明。
@@ -128,7 +128,37 @@
 
 ## 🆕 最近更新
 
-### v6.0.0 (最新版)
+### v6.0.2 (最新版)
+- **模組化拆分與效能提升**：
+  - **職責解耦**：將檔案存取、YAML 解析與快取邏輯抽離至獨立模組 [`src/skills-manager.ts`](src/skills-manager.ts)，主程式 [`src/server.ts`](src/server.ts) 專注於 MCP 路由註冊。
+  - **O(1) 雙向快取**：引入大小寫不敏感的 Map 雙向鍵值快取（以技能名與目錄名為 Key），將原本 $O(N)$ 的陣列雙重遍歷優化為 $O(1)$ 的直接讀取。
+  - **非同步 I/O 管線**：全面以 `fs/promises` 代替同步磁碟操作，搭配 `Promise.all` 併發枚舉，釋放 Node.js 事件循環阻塞。
+  - **Markdown 內容快取**：快取已剝離 YAML frontmatter 的技能文檔，避免工具頻繁調用時對硬碟的重複讀寫損耗。
+- **安全性深度防禦**：
+  - **防範 ReDoS 攻擊**：棄用非貪婪正則，重構為「逐行 Frontmatter 解析器」，規避了惡意/損壞 Markdown 導致的 CPU 回溯鎖死風險，且支援了 YAML 多行 `description` 欄位。
+  - **路徑遍歷（Path Traversal）防禦**：對 `skill_name` 輸入參數使用英數白名單篩選（`/^[a-zA-Z0-9-_]+$/`）。
+  - **絕對路徑防洩露**：安全捕獲原生 I/O 錯誤，隱蔽主機真實實體路徑與帳號名稱，回傳通用 `McpError`。
+  - **環境路徑與指令碼加固**：檢測 `SKILLS_PATH` 防範根目錄惡意注入；修復 `esbuild.js` 在 Windows 上的 `chmodSync` 崩潰問題，並在 `copy-skills.js` 中跳過符號連結 (Symlink) 杜絕遞迴拷貝死循環。
+
+- **上游安全更新同步**：套用來自 obra/superpowers v6.1.1 的安全加固：
+  - **WebSocket 影格長度限制**：在 `decodeFrame()` 中新增 `MAX_FRAME_PAYLOAD_BYTES (10 MB)` 檢測，防止超大型影格攻擊（CWE-789）。
+  - **硬連結限制**：在 `isRegularFileInsideContentDir()` 中加入 `stat.nlink !== 1` 檢測，防止透過硬連結 (Hardlink) 繞過路徑遍歷。
+  - **提取 `escapeHtmlText()`**：將行內的 `escHtml` 閉包提取為可重複使用的具名函數，以確保 HTML 逸出的一致性。
+  - **URL 解析重構**：抽離出 `pathnameOf()` and `queryKey()` 輔助函數，減少 `handleRequest()` 中的重複 URL 解析。
+- **`review-package` 路徑解析修正**：修復 `sdd-workspace` 呼叫，改用絕對路徑解析 (`$(cd "$(dirname "$0")" && pwd)`) 以防止與工作路徑 (CWD) 依賴相關的調用失敗。
+- **Windows 原生輔助腳本**：新增 Visual Companion 啟動/關閉、SDD review/task helper，以及 systematic-debugging polluter detection 的 PowerShell wrapper。
+- **技能文檔改進**：
+  - `subagent-driven-development`：新增 `plan-mandated` 審查指引，以處理計畫之間的衝突。
+  - `writing-skills`：結合字詞測試的實證，強化「禁止撰寫步驟清單 (recipes) 技能」的指引。
+  - `test-driven-development`：修正表格格式以提升清晰度。
+  - `writing-skills/anthropic-best-practices`：更新圖片的 CDN 網址。
+- **`helper.js` 註解對齊**：新增 4 個說明的行內註解以對齊上游文檔。保留 DOM 安全的 `showTombstone()` 實作（無 `innerHTML` 退化）。
+- **清理**：移除了已廢棄的 `walkthrough.md` (v5.1.0 升級指南)。
+
+### v6.0.1
+- **安全性修復 — Reflected XSS (#2)**: 修復 `skills/brainstorming/scripts/server.cjs` 中的伺服器端反射型跨站腳本漏洞。原本 `bootstrapPage()` 使用使用者提供的 `keyFromQuery` 參數（雖已通過 `timingSafeEqualStr` 驗證），現改為使用伺服器端 `TOKEN` 常數，徹底消除使用者可控資料進入 HTML 回應的風險。行為完全不變（驗證後的值相同）。
+
+### v6.0.0
 - **同步上游 obra/superpowers v6.1.1**: 大規模同步，引入上游對所有技能的改進。
 - **subagent-driven-development 流程改造**: 將原本的兩階段審查（規格 → 程式碼品質）合併為單一 **task reviewer** 子代理，並在最後增加 **whole-branch final review**。新增 **Pre-Flight Plan Review** 在執行前掃描任務衝突。新增 **Model Selection Guidance** 以最佳化成本與回合數。
 - **using-superpowers 簡化**: 移除平台特定說明與 Graphviz 圖表，改為 **各平台獨立參考檔案**（新增 `antigravity-tools.md`、`pi-tools.md`，更新 `codex-tools.md`），更乾淨地支援多種 AI 環境。