jfox-cli 0.1.0__py3-none-any.whl

jfox/indexer.py

@@ -0,0 +1,366 @@
+"""
+File system indexer with watchdog for auto-indexing Zettelkasten notes.
+
+Provides:
+- Real-time file monitoring
+- Automatic indexing on file changes
+- Batch indexing for initial setup
+- Index status and statistics
+"""
+
+import os
+import time
+import threading
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Set
+from dataclasses import dataclass, field
+from datetime import datetime
+from collections import deque
+
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler, FileModifiedEvent, FileCreatedEvent, FileDeletedEvent
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from .config import ZKConfig
+from .models import Note
+from .vector_store import VectorStore
+from .graph import KnowledgeGraph
+
+
+console = Console()
+
+
+@dataclass
+class IndexStats:
+    """Statistics for the indexer."""
+    total_indexed: int = 0
+    last_indexed: Optional[datetime] = None
+    pending_changes: int = 0
+    errors: List[str] = field(default_factory=list)
+
+
+class NoteEventHandler(FileSystemEventHandler):
+    """
+    Handles file system events for note files.
+    
+    Debounces rapid file changes and batches indexing operations.
+    """
+    
+    def __init__(
+        self,
+        vector_store: VectorStore,
+        config: ZKConfig,
+        debounce_seconds: float = 1.0,
+        callback: Optional[Callable[[str, str], None]] = None
+    ):
+        self.vector_store = vector_store
+        self.config = config
+        self.debounce_seconds = debounce_seconds
+        self.callback = callback
+        
+        self._pending: Dict[str, float] = {}
+        self._lock = threading.Lock()
+        self._timer: Optional[threading.Timer] = None
+        self.stats = IndexStats()
+    
+    def on_modified(self, event):
+        if event.is_directory:
+            return
+        if not event.src_path.endswith(".md"):
+            return
+        
+        with self._lock:
+            self._pending[event.src_path] = time.time()
+            self._schedule_process()
+    
+    on_created = on_modified  # Treat creation same as modification
+    
+    def on_deleted(self, event):
+        if event.is_directory:
+            return
+        if not event.src_path.endswith(".md"):
+            return
+        
+        # Remove from vector store
+        note_id = Path(event.src_path).stem
+        try:
+            self.vector_store.delete_note(note_id)
+            if self.callback:
+                self.callback("deleted", note_id)
+        except Exception as e:
+            self.stats.errors.append(f"Failed to delete {note_id}: {e}")
+    
+    def _schedule_process(self):
+        """Schedule processing of pending changes."""
+        if self._timer:
+            self._timer.cancel()
+        
+        self._timer = threading.Timer(self.debounce_seconds, self._process_pending)
+        self._timer.daemon = True
+        self._timer.start()
+    
+    def _process_pending(self):
+        """Process all pending file changes."""
+        with self._lock:
+            now = time.time()
+            ready = [
+                path for path, timestamp in self._pending.items()
+                if now - timestamp >= self.debounce_seconds
+            ]
+            
+            for path in ready:
+                del self._pending[path]
+            
+            self.stats.pending_changes = len(self._pending)
+        
+        for path in ready:
+            self._index_file(path)
+    
+    def _index_file(self, file_path: str):
+        """Index a single note file."""
+        from .note import NoteManager
+        
+        try:
+            note = NoteManager.load_note(Path(file_path))
+            if not note:
+                return
+            
+            # Index in vector store
+            self.vector_store.add_or_update_note(note)
+            
+            self.stats.total_indexed += 1
+            self.stats.last_indexed = datetime.now()
+            
+            if self.callback:
+                self.callback("indexed", note.id)
+                
+        except Exception as e:
+            error_msg = f"Failed to index {file_path}: {e}"
+            self.stats.errors.append(error_msg)
+            if self.callback:
+                self.callback("error", error_msg)
+
+
+class Indexer:
+    """
+    Manages file system monitoring and indexing for Zettelkasten notes.
+    
+    Usage:
+        indexer = Indexer(config, vector_store)
+        indexer.start()  # Start watching
+        ...
+        indexer.stop()   # Stop watching
+    """
+    
+    def __init__(
+        self,
+        config: ZKConfig,
+        vector_store: VectorStore,
+        debounce_seconds: float = 1.0
+    ):
+        self.config = config
+        self.vector_store = vector_store
+        self.debounce_seconds = debounce_seconds
+        
+        self._observer: Optional[Observer] = None
+        self._handler: Optional[NoteEventHandler] = None
+        self._running = False
+    
+    def start(self, callback: Optional[Callable[[str, str], None]] = None):
+        """
+        Start the file system observer.
+        
+        Args:
+            callback: Optional callback for events (event_type, message)
+        """
+        if self._running:
+            return
+        
+        notes_dir = Path(self.config.notes_dir)
+        if not notes_dir.exists():
+            console.print(f"[yellow]Notes directory not found: {notes_dir}[/yellow]")
+            return
+        
+        self._handler = NoteEventHandler(
+            self.vector_store,
+            self.config,
+            self.debounce_seconds,
+            callback
+        )
+        
+        self._observer = Observer()
+        self._observer.schedule(self._handler, str(notes_dir), recursive=True)
+        self._observer.start()
+        
+        self._running = True
+        console.print(f"[green]Started indexer watching: {notes_dir}[/green]")
+    
+    def stop(self):
+        """Stop the file system observer."""
+        if not self._running:
+            return
+        
+        if self._observer:
+            self._observer.stop()
+            self._observer.join()
+        
+        self._running = False
+        console.print("[green]Indexer stopped[/green]")
+    
+    def is_running(self) -> bool:
+        """Check if the indexer is running."""
+        return self._running
+    
+    def get_stats(self) -> IndexStats:
+        """Get indexer statistics."""
+        if self._handler:
+            return self._handler.stats
+        return IndexStats()
+    
+    def index_all(self, progress_callback: Optional[Callable[[int, int], None]] = None) -> int:
+        """
+        Perform full re-indexing of all notes.
+        
+        Args:
+            progress_callback: Called with (current, total) for progress updates
+            
+        Returns:
+            Number of notes indexed
+        """
+        from .note import NoteManager
+        
+        notes_dir = Path(self.config.notes_dir)
+        if not notes_dir.exists():
+            return 0
+        
+        # Find all note files
+        note_files = list(notes_dir.rglob("*.md"))
+        total = len(note_files)
+        
+        if total == 0:
+            return 0
+        
+        indexed = 0
+        
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console
+        ) as progress:
+            task = progress.add_task(f"Indexing {total} notes...", total=total)
+            
+            for i, note_file in enumerate(note_files):
+                try:
+                    note = NoteManager.load_note(note_file)
+                    if note:
+                        self.vector_store.add_or_update_note(note)
+                        indexed += 1
+                        
+                        if self._handler:
+                            self._handler.stats.total_indexed += 1
+                    
+                    progress.update(task, advance=1)
+                    
+                    if progress_callback:
+                        progress_callback(i + 1, total)
+                        
+                except Exception as e:
+                    console.print(f"[red]Failed to index {note_file}: {e}[/red]")
+        
+        return indexed
+    
+    def index_note(self, note_id: str) -> bool:
+        """
+        Index a specific note by ID.
+        
+        Args:
+            note_id: The note ID to index
+            
+        Returns:
+            True if successful
+        """
+        from .note import NoteManager
+        
+        note_file = NoteManager.find_note_file(self.config, note_id)
+        if not note_file:
+            return False
+        
+        try:
+            note = NoteManager.load_note(note_file)
+            if note:
+                self.vector_store.add_or_update_note(note)
+                return True
+        except Exception as e:
+            console.print(f"[red]Failed to index {note_id}: {e}[/red]")
+        
+        return False
+    
+    def verify_index(self) -> Dict[str, any]:
+        """
+        Verify the index integrity.
+        
+        Returns:
+            Dict with verification results
+        """
+        from .note import NoteManager
+        
+        notes_dir = Path(self.config.notes_dir)
+        if not notes_dir.exists():
+            return {"error": "Notes directory not found"}
+        
+        # Get all note files
+        note_files = list(notes_dir.rglob("*.md"))
+        file_ids = {f.stem for f in note_files}
+        
+        # Get all indexed notes
+        indexed_ids = set(self.vector_store.get_all_ids())
+        
+        missing_from_index = file_ids - indexed_ids
+        orphaned_in_index = indexed_ids - file_ids
+        
+        return {
+            "total_files": len(file_ids),
+            "total_indexed": len(indexed_ids),
+            "missing_from_index": list(missing_from_index),
+            "orphaned_in_index": list(orphaned_in_index),
+            "healthy": len(missing_from_index) == 0 and len(orphaned_in_index) == 0
+        }
+
+
+class IndexerDaemon:
+    """
+    Daemon wrapper for running indexer in background.
+    
+    Usage:
+        daemon = IndexerDaemon(config, vector_store)
+        daemon.run()  # Blocks until stopped
+    """
+    
+    def __init__(self, config: ZKConfig, vector_store: VectorStore):
+        self.indexer = Indexer(config, vector_store)
+        self._stop_event = threading.Event()
+    
+    def run(self):
+        """Run the daemon until stopped."""
+        self.indexer.start(callback=self._on_event)
+        
+        try:
+            while not self._stop_event.is_set():
+                self._stop_event.wait(1)
+        except KeyboardInterrupt:
+            pass
+        finally:
+            self.indexer.stop()
+    
+    def stop(self):
+        """Signal the daemon to stop."""
+        self._stop_event.set()
+    
+    def _on_event(self, event_type: str, message: str):
+        """Handle indexer events."""
+        timestamp = datetime.now().strftime("%H:%M:%S")
+        if event_type == "error":
+            console.print(f"[{timestamp}] [red]Error: {message}[/red]")
+        else:
+            console.print(f"[{timestamp}] [green]{event_type}: {message}[/green]")

jfox/kb_manager.py

@@ -0,0 +1,316 @@
+"""
+知识库管理器 - 高级知识库操作
+
+提供知识库的创建、删除、统计等功能
+"""
+
+import shutil
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+
+from .global_config import (
+    GlobalConfigManager, 
+    KnowledgeBaseEntry, 
+    get_global_config_manager,
+    DEFAULT_KB_PATH
+)
+from .config import ZKConfig
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class KBStats:
+    """知识库统计信息"""
+    name: str
+    path: Path
+    total_notes: int
+    by_type: Dict[str, int]
+    created: Optional[str] = None
+    last_used: Optional[str] = None
+    description: Optional[str] = None
+    is_current: bool = False
+
+
+class KnowledgeBaseManager:
+    """
+    知识库管理器
+    
+    提供知识库的完整生命周期管理：
+    - 创建、删除、重命名
+    - 统计信息
+    - 切换默认知识库
+    """
+    
+    def __init__(self, config_manager: Optional[GlobalConfigManager] = None):
+        self.config_manager = config_manager or get_global_config_manager()
+    
+    def create(
+        self, 
+        name: str, 
+        path: Optional[Path] = None,
+        description: Optional[str] = None,
+        set_as_default: bool = False
+    ) -> tuple[bool, str]:
+        """
+        创建新知识库
+        
+        Args:
+            name: 知识库名称
+            path: 存储路径（默认 ~/.zettelkasten/<name>/）
+            description: 描述
+            set_as_default: 是否设为默认
+            
+        Returns:
+            (success, message)
+        """
+        # 检查名称是否已存在
+        if self.config_manager.kb_exists(name):
+            return False, f"Knowledge base '{name}' already exists"
+
+        # 检查名称不与保留目录冲突（default KB 的内部目录）
+        reserved_names = {"notes", ".zk", ".zk_config.json"}
+        if name.lower() in reserved_names:
+            return False, f"Name '{name}' is reserved and cannot be used as a KB name"
+        
+        # 确定路径（统一管理到 ~/.zettelkasten/ 下）
+        if path is None:
+            if name == "default":
+                path = DEFAULT_KB_PATH
+            else:
+                path = DEFAULT_KB_PATH / name
+
+        path = path.expanduser().resolve()
+
+        # 校验路径必须在统一管理目录下
+        kb_root = DEFAULT_KB_PATH.resolve()
+        try:
+            path.relative_to(kb_root)
+        except ValueError:
+            return (
+                False,
+                f"Path '{path}' is outside managed directory '{kb_root}'. "
+                f"All knowledge bases must be under {kb_root}/",
+            )
+
+        # 检查路径是否已被其他知识库使用
+        for kb in self.config_manager.list_knowledge_bases():
+            if Path(kb.path) == path:
+                return False, f"Path '{path}' is already used by another knowledge base"
+        
+        # 创建目录结构
+        try:
+            config = ZKConfig(base_dir=path)
+            config.ensure_dirs()
+            
+            # 添加到配置
+            if not self.config_manager.add_knowledge_base(name, path, description):
+                return False, "Failed to register knowledge base"
+            
+            # 设为默认（如果需要）
+            if set_as_default:
+                self.config_manager.set_default(name)
+            
+            return True, f"Created knowledge base '{name}' at {path}"
+            
+        except Exception as e:
+            logger.error(f"Failed to create knowledge base: {e}")
+            return False, str(e)
+    
+    def remove(
+        self, 
+        name: str, 
+        delete_data: bool = False
+    ) -> tuple[bool, str]:
+        """
+        移除知识库
+        
+        Args:
+            name: 知识库名称
+            delete_data: 是否删除实际数据
+            
+        Returns:
+            (success, message)
+        """
+        if not self.config_manager.kb_exists(name):
+            return False, f"Knowledge base '{name}' not found"
+        
+        # 获取路径
+        path = self.config_manager.get_kb_path(name)
+        
+        # 从配置中移除
+        if not self.config_manager.remove_knowledge_base(name):
+            return False, "Failed to unregister knowledge base"
+        
+        # 删除数据（如果需要）
+        if delete_data and path and path.exists():
+            # 禁止删除 default KB 的数据目录，因为其他命名 KB 也在其中
+            if path.resolve() == DEFAULT_KB_PATH.resolve():
+                return (
+                    True,
+                    f"Removed knowledge base '{name}' from config, "
+                    f"but cannot delete data: default KB directory contains other KBs",
+                )
+            try:
+                shutil.rmtree(path)
+                return True, f"Removed knowledge base '{name}' and deleted all data"
+            except Exception as e:
+                return True, f"Removed knowledge base '{name}' but failed to delete data: {e}"
+        
+        return True, f"Removed knowledge base '{name}' (data preserved at {path})"
+    
+    def rename(self, old_name: str, new_name: str) -> tuple[bool, str]:
+        """
+        重命名知识库
+        
+        Args:
+            old_name: 原名称
+            new_name: 新名称
+            
+        Returns:
+            (success, message)
+        """
+        if not self.config_manager.kb_exists(old_name):
+            return False, f"Knowledge base '{old_name}' not found"
+        
+        if self.config_manager.kb_exists(new_name):
+            return False, f"Knowledge base '{new_name}' already exists"
+        
+        if self.config_manager.rename_knowledge_base(old_name, new_name):
+            return True, f"Renamed '{old_name}' to '{new_name}'"
+        
+        return False, "Failed to rename knowledge base"
+    
+    def switch(self, name: str) -> tuple[bool, str]:
+        """
+        切换默认知识库
+        
+        Args:
+            name: 知识库名称
+            
+        Returns:
+            (success, message)
+        """
+        if not self.config_manager.kb_exists(name):
+            return False, f"Knowledge base '{name}' not found"
+        
+        # 更新最后使用时间
+        self.config_manager.update_last_used(name)
+        
+        if self.config_manager.set_default(name):
+            path = self.config_manager.get_kb_path(name)
+            return True, f"Switched to '{name}' ({path})"
+        
+        return False, "Failed to switch knowledge base"
+    
+    def list_all(self) -> List[KBStats]:
+        """
+        列出所有知识库及其统计信息
+        
+        Returns:
+            知识库统计信息列表
+        """
+        entries = self.config_manager.list_knowledge_bases()
+        current = self.config_manager.get_default_kb_name()
+        
+        stats_list = []
+        for entry in entries:
+            stats = self._get_kb_stats(entry)
+            stats.is_current = (entry.name == current)
+            stats_list.append(stats)
+        
+        return stats_list
+    
+    def get_info(self, name: str) -> Optional[KBStats]:
+        """
+        获取知识库详细信息
+        
+        Args:
+            name: 知识库名称
+            
+        Returns:
+            知识库统计信息，不存在则返回 None
+        """
+        if not self.config_manager.kb_exists(name):
+            return None
+        
+        entries = self.config_manager.list_knowledge_bases()
+        for entry in entries:
+            if entry.name == name:
+                stats = self._get_kb_stats(entry)
+                stats.is_current = (name == self.config_manager.get_default_kb_name())
+                return stats
+        
+        return None
+    
+    def _get_kb_stats(self, entry: KnowledgeBaseEntry) -> KBStats:
+        """获取知识库统计信息"""
+        path = Path(entry.path)
+        
+        # 统计笔记数量
+        total = 0
+        by_type = {"fleeting": 0, "literature": 0, "permanent": 0}
+        
+        if path.exists():
+            notes_dir = path / "notes"
+            if notes_dir.exists():
+                for note_type in ["fleeting", "literature", "permanent"]:
+                    type_dir = notes_dir / note_type
+                    if type_dir.exists():
+                        count = len(list(type_dir.glob("*.md")))
+                        by_type[note_type] = count
+                        total += count
+        
+        return KBStats(
+            name=entry.name,
+            path=path,
+            total_notes=total,
+            by_type=by_type,
+            created=entry.created,
+            last_used=entry.last_used,
+            description=entry.description,
+            is_current=False,
+        )
+    
+    def get_current_kb_info(self) -> Optional[KBStats]:
+        """获取当前默认知识库信息"""
+        current_name = self.config_manager.get_default_kb_name()
+        return self.get_info(current_name)
+    
+    def ensure_default_exists(self) -> bool:
+        """
+        确保默认知识库存在，如果不存在则创建
+        
+        Returns:
+            是否成功
+        """
+        default_name = self.config_manager.get_default_kb_name()
+        
+        if not self.config_manager.kb_exists(default_name):
+            # 创建默认知识库
+            path = self.config_manager.get_default_kb_path()
+            success, _ = self.create(
+                name=default_name,
+                path=path,
+                description="Default knowledge base",
+                set_as_default=True
+            )
+            return success
+        
+        return True
+
+
+# 全局知识库管理器实例
+_kb_manager: Optional[KnowledgeBaseManager] = None
+
+
+def get_kb_manager() -> KnowledgeBaseManager:
+    """获取知识库管理器实例"""
+    global _kb_manager
+    if _kb_manager is None:
+        _kb_manager = KnowledgeBaseManager()
+    return _kb_manager