fix: filter generated docs from change detection, merge metadata, async I/O

- Filter output_dir and .codewiki/ from untracked files in git change
  detection so generated docs don't falsely trigger incremental updates
- Merge into existing metadata.json on close_session to preserve stats
  from other workflows (e.g. CLI generate_docs)
- Remove unused format_user_prompt import in prompt_server.py
- Replace mutable default list argument with None in module_tree.py
- Route blocking file I/O (read_text/write_text/exists/mkdir) through
  asyncio.to_thread() in doc_writer.py to avoid blocking MCP event loop

Author: mambo-wang

codewiki/mcp/server.py

@@ -546,9 +546,9 @@ def _text(content: str) -> TextContent:
 def _write_generation_metadata(session: SessionState) -> None:
     """Write ``metadata.json`` to the session's output directory.
 
-    Records the current git commit and timestamp so that
-    :func:`_detect_changes` can diff against this baseline on the next
-    ``analyze_repo`` call, enabling incremental updates.
+    Merges the current git commit and timestamp into any existing metadata
+    so that stats from other workflows (e.g. CLI ``generate_docs``) are
+    preserved.
     """
     try:
         output_dir = Path(session.output_dir)
@@ -563,14 +563,23 @@ def _write_generation_metadata(session: SessionState) -> None:
             pass
 
         from datetime import datetime
-        metadata = {
-            "generation_info": {
-                "commit_id": commit_id,
-                "timestamp": datetime.now().isoformat(),
-            },
+
+        # Read existing metadata (if any) and merge
+        metadata_path = output_dir / "metadata.json"
+        existing: dict = {}
+        if metadata_path.exists():
+            try:
+                existing = json.loads(metadata_path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        existing["generation_info"] = {
+            **existing.get("generation_info", {}),
+            "commit_id": commit_id,
+            "timestamp": datetime.now().isoformat(),
         }
-        (output_dir / "metadata.json").write_text(
-            json.dumps(metadata, indent=2, ensure_ascii=False),
+        metadata_path.write_text(
+            json.dumps(existing, indent=2, ensure_ascii=False),
             encoding="utf-8",
         )
     except Exception as e:

codewiki/mcp/tools/analysis.py

@@ -52,7 +52,7 @@ def _detect_changes(
         return None
 
     # Try git-based detection first
-    changes = _detect_via_git(repo_path, metadata)
+    changes = _detect_via_git(repo_path, metadata, output_dir)
 
     # Fallback to mtime-based detection
     if changes is None:
@@ -90,6 +90,7 @@ def _detect_changes(
 def _detect_via_git(
     repo_path: Path,
     metadata: Dict[str, Any],
+    output_dir: Path | None = None,
 ) -> Optional[Dict[str, Any]]:
     """Detect changes via git. Returns None if not in a git repo or if no
     previous commit is recorded (so the caller can fall through to mtime).
@@ -146,6 +147,16 @@ def _detect_via_git(
             pass
 
     # 2) Uncommitted changes: staged (index vs HEAD) + unstaged (working tree vs index) + untracked
+    # Compute output_dir relative prefix so we can skip generated docs
+    output_dir_rel = ""
+    if output_dir is not None:
+        try:
+            output_dir_rel = Path(output_dir).resolve().relative_to(repo_root).as_posix()
+            if output_dir_rel == ".":
+                output_dir_rel = ""
+        except (ValueError, TypeError):
+            pass
+
     try:
         for d in list(repo.index.diff("HEAD")) + list(repo.index.diff(None)):
             p = d.a_path
@@ -163,6 +174,11 @@ def _detect_via_git(
                     p = p[len(subpath) + 1:]
                 else:
                     continue
+            # Skip generated docs and session workspace files
+            if p.startswith(".codewiki/"):
+                continue
+            if output_dir_rel and (p == output_dir_rel or p.startswith(output_dir_rel + "/")):
+                continue
             if p not in changed:
                 changed.append(p)
     except Exception:

codewiki/mcp/tools/doc_writer.py

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
 from pathlib import Path
@@ -86,14 +87,14 @@ async def handle_write_doc_file(
 
     content = arguments["content"]
 
-    _ensure_parent_dirs(doc_path)
+    await asyncio.to_thread(_ensure_parent_dirs, doc_path)
 
-    if doc_path.exists():
+    if await asyncio.to_thread(doc_path.exists):
         return json.dumps({
             "error": f"File already exists: {filename}. Use edit_doc_file to modify it."
         })
 
-    doc_path.write_text(content, encoding="utf-8")
+    await asyncio.to_thread(doc_path.write_text, content, "utf-8")
 
     # Mermaid validation
     mermaid_result = await _validate_mermaid(str(doc_path), filename)
@@ -136,7 +137,7 @@ async def handle_edit_doc_file(
         old_content = path_history.pop()
         history[str(doc_path)] = path_history
         session.registry["file_history"] = history
-        doc_path.write_text(old_content, encoding="utf-8")
+        await asyncio.to_thread(doc_path.write_text, old_content, "utf-8")
 
         # Validate Mermaid after undo
         mermaid_result = await _validate_mermaid(str(doc_path), filename)
@@ -146,11 +147,11 @@ async def handle_edit_doc_file(
             "mermaid_validation": mermaid_result,
         }, ensure_ascii=False)
 
-    if not doc_path.exists():
+    if not await asyncio.to_thread(doc_path.exists):
         return json.dumps({"error": f"File not found: {filename}. Use write_doc_file to create it."})
 
     # Save current content to history before editing
-    current_content = doc_path.read_text(encoding="utf-8")
+    current_content = await asyncio.to_thread(doc_path.read_text, "utf-8")
     _save_history(session, doc_path, current_content)
 
     if command == "str_replace":
@@ -166,7 +167,7 @@ async def handle_edit_doc_file(
             return json.dumps({"error": f"old_str appears {occurrences} times in {filename}. Make it unique."})
 
         new_content = current_content.replace(old_str, new_str, 1)
-        doc_path.write_text(new_content, encoding="utf-8")
+        await asyncio.to_thread(doc_path.write_text, new_content, "utf-8")
 
         # Snippet around the edit
         replacement_line = current_content.split(old_str)[0].count("\n")
@@ -186,7 +187,7 @@ async def handle_edit_doc_file(
         new_str_lines = new_str.split("\n")
         lines = lines[:insert_line] + new_str_lines + lines[insert_line:]
         new_content = "\n".join(lines)
-        doc_path.write_text(new_content, encoding="utf-8")
+        await asyncio.to_thread(doc_path.write_text, new_content, "utf-8")
 
         start = max(0, insert_line - 4)
         end = min(len(lines), start + len(new_str_lines) + 8)

codewiki/mcp/tools/module_tree.py

@@ -19,12 +19,14 @@
 logger = logging.getLogger(__name__)
 
 
-def _get_processing_order(module_tree: Dict[str, Any], parent_path: List[str] = []) -> List[Dict[str, Any]]:
+def _get_processing_order(module_tree: Dict[str, Any], parent_path: List[str] | None = None) -> List[Dict[str, Any]]:
     """Compute leaf-first processing order from a module tree.
 
     Returns a list of dicts with module path, name, leaf status, and
     component/children info.
     """
+    if parent_path is None:
+        parent_path = []
     order: List[Dict[str, Any]] = []
 
     def _collect(tree: Dict[str, Any], path: List[str]) -> None:

codewiki/mcp/tools/prompt_server.py

@@ -19,7 +19,6 @@
     format_system_prompt,
     format_leaf_system_prompt,
     format_cluster_prompt,
-    format_user_prompt,
 )