CopilotTaskMaster 0.1.1__py3-none-any.whl

taskmaster/search.py

@@ -0,0 +1,241 @@
+"""
+Task Searcher - Search functionality for task cards
+"""
+
+import re
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Set
+import frontmatter
+
+
+class TaskSearcher:
+    """Searches markdown task cards efficiently"""
+    
+    def __init__(self, base_path: str):
+        """
+        Initialize TaskSearcher
+        
+        Args:
+            base_path: Root directory for task cards
+        """
+        self.base_path = Path(base_path).resolve()
+    
+    def search(
+        self,
+        query: str = "",
+        metadata_filters: Optional[Dict[str, Any]] = None,
+        path_pattern: str = "",
+        max_results: int = 50,
+        include_content: bool = False
+    ) -> List[Dict[str, Any]]:
+        """
+        Search tasks with text and metadata filters
+        
+        Args:
+            query: Text to search in title and content
+            metadata_filters: Dict of metadata key-value pairs to filter by
+            path_pattern: Glob pattern to filter paths (e.g., 'project1/**')
+            max_results: Maximum number of results to return
+            include_content: Include full content in results (token-expensive)
+        
+        Returns:
+            List of matching tasks with relevance scores
+        """
+        if not self.base_path.exists():
+            return []
+        
+        pattern = f"{path_pattern}/*.md" if path_pattern and not path_pattern.endswith('.md') else "**/*.md"
+        results = []
+        query_lower = query.lower() if query else ""
+        
+        for md_file in self.base_path.glob(pattern):
+            try:
+                with open(md_file, 'r', encoding='utf-8') as f:
+                    post = frontmatter.load(f)
+                
+                # Apply metadata filters
+                if metadata_filters:
+                    if not self._matches_metadata(post.metadata, metadata_filters):
+                        continue
+                
+                # Calculate relevance score
+                score = 0
+                title = post.get('title', '')
+                content = post.content
+                
+                if query_lower:
+                    # Title matches are weighted higher
+                    if query_lower in title.lower():
+                        score += 10
+                    
+                    # Content matches
+                    content_matches = content.lower().count(query_lower)
+                    score += content_matches
+                    
+                    # Skip if no matches
+                    if score == 0:
+                        continue
+                else:
+                    # If no query, all filtered tasks get score 1
+                    score = 1
+                
+                result = {
+                    'path': md_file.relative_to(self.base_path).as_posix(),
+                    'title': title,
+                    'score': score,
+                    'metadata': post.metadata
+                }
+                
+                if include_content:
+                    result['content'] = content
+                else:
+                    # Include a snippet if there's a query match
+                    if query_lower and query_lower in content.lower():
+                        result['snippet'] = self._extract_snippet(content, query_lower)
+                
+                results.append(result)
+
+                # Early exit for performance: stop scanning once we have enough results
+                if len(results) >= max_results:
+                    break
+
+            except Exception as e:
+                continue
+        
+        # Sort by relevance score
+        results.sort(key=lambda x: x['score'], reverse=True)
+        
+        return results[:max_results]
+    
+    def search_by_tags(
+        self,
+        tags: List[str],
+        match_all: bool = False,
+        max_results: int = 50
+    ) -> List[Dict[str, Any]]:
+        """
+        Search tasks by tags
+        
+        Args:
+            tags: List of tags to search for
+            match_all: If True, task must have all tags. If False, any tag matches
+            max_results: Maximum number of results
+        
+        Returns:
+            List of matching tasks
+        """
+        tags_lower = [tag.lower() for tag in tags]
+        results = []
+        if not tags_lower:
+            return results
+
+        for md_file in self.base_path.glob("**/*.md"):
+            try:
+                with open(md_file, 'r', encoding='utf-8') as f:
+                    post = frontmatter.load(f)
+
+                if self._matches_metadata(post.metadata, {'tags': tags_lower}, match_all=match_all):
+                    results.append({
+                        'path': md_file.relative_to(self.base_path).as_posix(),
+                        'title': post.get('title', ''),
+                        'metadata': post.metadata
+                    })
+
+                if len(results) >= max_results:
+                    break
+            except Exception:
+                continue
+
+        return results
+    
+    def get_all_tags(self, project: Optional[str] = None) -> Set[str]:
+        """
+        Get all unique tags, optionally scoped to a project directory
+        
+        Args:
+            project: Optional project name to scope tag collection
+        
+        Returns:
+            Set of all tags
+        """
+        tags = set()
+
+        # Determine search root based on project param
+        if project:
+            search_root = self.base_path / project
+            if not search_root.exists():
+                return tags
+            iterator = search_root.glob("**/*.md")
+        else:
+            iterator = self.base_path.glob("**/*.md")
+        
+        for md_file in iterator:
+            try:
+                with open(md_file, 'r', encoding='utf-8') as f:
+                    post = frontmatter.load(f)
+                
+                task_tags = post.metadata.get('tags', [])
+                if isinstance(task_tags, str):
+                    task_tags = [task_tags]
+                # Normalize tags to lowercase strings
+                tags.update(str(t).lower() for t in task_tags)
+            except Exception:
+                continue
+        
+        return tags
+    
+    def _matches_metadata(self, metadata: Dict[str, Any], filters: Dict[str, Any], match_all: bool = False) -> bool:
+        """Check if metadata matches all filters (case-insensitive, flexible list/scalar handling)
+
+        For list-valued filters:
+            - if match_all is False (default): return True if any filter value is present in metadata
+            - if match_all is True: return True only if all filter values are present in metadata
+        """
+        for key, value in filters.items():
+            if key not in metadata:
+                return False
+
+            meta_value = metadata[key]
+
+            # Normalize metadata values to list of lowercase strings
+            if isinstance(meta_value, str):
+                meta_list = [meta_value.lower()]
+            elif isinstance(meta_value, list):
+                meta_list = [str(v).lower() for v in meta_value]
+            else:
+                meta_list = [str(meta_value).lower()]
+
+            # Normalize filter values to list of lowercase strings
+            if isinstance(value, list):
+                filter_list = [str(v).lower() for v in value]
+                if match_all:
+                    if not all(f in meta_list for f in filter_list):
+                        return False
+                else:
+                    if not any(f in meta_list for f in filter_list):
+                        return False
+            else:
+                if str(value).lower() not in meta_list:
+                    return False
+
+        return True
+    
+    def _extract_snippet(self, content: str, query: str, context_chars: int = 100) -> str:
+        """Extract a snippet around the query match"""
+        query_lower = query.lower()
+        content_lower = content.lower()
+        
+        index = content_lower.find(query_lower)
+        if index == -1:
+            return content[:200] + "..." if len(content) > 200 else content
+        
+        start = max(0, index - context_chars)
+        end = min(len(content), index + len(query) + context_chars)
+        
+        snippet = content[start:end]
+        if start > 0:
+            snippet = "..." + snippet
+        if end < len(content):
+            snippet = snippet + "..."
+        
+        return snippet

taskmaster/task_manager.py

@@ -0,0 +1,388 @@
+"""
+Task Manager - Core functionality for managing markdown task cards
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+from datetime import datetime
+import frontmatter
+
+
+class TaskManager:
+    """Manages markdown task cards in a hierarchical folder structure"""
+    
+    def __init__(self, base_path: str = None):
+        """
+        Initialize TaskManager
+        
+        Args:
+            base_path: Root directory for task cards. Defaults to TASKMASTER_TASKS_DIR env var or ./tasks
+        """
+        if base_path is None:
+            base_path = os.environ.get('TASKMASTER_TASKS_DIR', './tasks')
+        self.base_path = Path(base_path).resolve()
+        self.base_path.mkdir(parents=True, exist_ok=True)
+
+    def _resolve_path(self, project: Optional[str], path: str):
+        """Resolve a (project, path) pair into a filesystem Path and a POSIX relative path.
+
+        Rules:
+        - If `path` includes a top-level folder (e.g., 'project/file.md'), that folder will be
+          treated as the project when `project` is not specified.
+        - If `project` is provided and `path` also includes a different project prefix, a
+          ValueError is raised to avoid ambiguity.
+        - If neither a project argument nor a project prefix in the path is available, a
+          ValueError is raised — callers must explicitly provide a project.
+        - `path` must be relative and must not contain parent ('..') references.
+        """
+        p = Path(path)
+        if p.is_absolute():
+            raise ValueError("path must be relative")
+        if any(part == ".." for part in p.parts):
+            raise ValueError("path must not contain parent references")
+
+        # If project is not provided, the first path part is treated as project when present.
+        if project is None:
+            if len(p.parts) >= 2:
+                project = p.parts[0]
+                rest = Path(*p.parts[1:])
+            else:
+                # No project specified anywhere: error out — callers must be explicit
+                raise ValueError("project must be specified either as argument or as the top-level folder in path")
+        else:
+            # Project was provided explicitly — interpret the path relative to that project.
+            # If the path redundantly includes the same project prefix (e.g., 'proj/file'), strip it.
+            if len(p.parts) >= 2 and p.parts[0] == project:
+                rest = Path(*p.parts[1:])
+            else:
+                rest = p
+
+        full_path = self.base_path / project / rest
+        relative_posix = full_path.relative_to(self.base_path).as_posix()
+        return full_path, relative_posix
+    
+    def create_task(
+        self,
+        path: str,
+        title: str,
+        content: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+        project: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new task card
+        
+        Args:
+            path: Relative path within project (e.g., 'task1.md') or with project prefix ('project1/task1.md')
+            project: Optional project name. If omitted, project will be inferred from the path or
+                     `default_project` will be used if configured.
+            title: Task title
+            content: Task content (markdown)
+            metadata: Additional metadata (status, priority, tags, etc.)
+        
+        Returns:
+            Dict with task information
+        """
+        full_path, rel_path = self._resolve_path(project, path)
+
+        # Ensure parent directories exist
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Create frontmatter document
+        post = frontmatter.Post(content)
+        post['title'] = title
+        post['created'] = datetime.now().isoformat()
+        post['updated'] = datetime.now().isoformat()
+        
+        if metadata:
+            post.metadata.update(metadata)
+        
+        # Write to file
+        with open(full_path, 'w', encoding='utf-8') as f:
+            f.write(frontmatter.dumps(post))
+        
+        return {
+            'path': rel_path,
+            'title': title,
+            'created': post['created'],
+            'metadata': post.metadata
+        }
+    
+    def read_task(self, path: str, project: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        """
+        Read a task card
+        
+        Args:
+            path: Relative path within project or with project prefix
+            project: Optional project name to scope the read
+        
+        Returns:
+            Dict with task information or None if not found
+        """
+        full_path, rel_path = self._resolve_path(project, path)
+        
+        if not full_path.exists():
+            return None
+        
+        with open(full_path, 'r', encoding='utf-8') as f:
+            post = frontmatter.load(f)
+        
+        return {
+            'path': rel_path,
+            'title': post.get('title', ''),
+            'content': post.content,
+            'metadata': post.metadata
+        }
+    
+    def update_task(
+        self,
+        path: str,
+        title: Optional[str] = None,
+        content: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        project: Optional[str] = None
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Update an existing task card
+        
+        Args:
+            path: Relative path within project or with project prefix
+            project: Optional project name to scope the update
+            title: New title (optional)
+            content: New content (optional)
+            metadata: Metadata to update (merged with existing)
+        
+        Returns:
+            Dict with updated task information or None if not found
+        """
+        full_path, rel_path = self._resolve_path(project, path)
+        
+        if not full_path.exists():
+            return None
+        
+        with open(full_path, 'r', encoding='utf-8') as f:
+            post = frontmatter.load(f)
+        
+        if title is not None:
+            post['title'] = title
+        
+        if content is not None:
+            post.content = content
+        
+        if metadata:
+            post.metadata.update(metadata)
+        
+        post['updated'] = datetime.now().isoformat()
+        
+        with open(full_path, 'w', encoding='utf-8') as f:
+            f.write(frontmatter.dumps(post))
+        
+        return {
+            'path': rel_path,
+            'title': post.get('title', ''),
+            'content': post.content,
+            'metadata': post.metadata
+        }
+    
+    def delete_task(self, path: str, project: Optional[str] = None) -> bool:
+        """
+        Delete a task card
+        
+        Args:
+            path: Relative path within project or with project prefix
+            project: Optional project name to scope the delete
+        
+        Returns:
+            True if deleted, False if not found
+        """
+        full_path, rel_path = self._resolve_path(project, path)
+        
+        if not full_path.exists():
+            return False
+        
+        full_path.unlink()
+        
+        # Clean up empty parent directories
+        try:
+            parent = full_path.parent
+            while parent != self.base_path and not any(parent.iterdir()):
+                parent.rmdir()
+                parent = parent.parent
+        except Exception:
+            pass
+        
+        return True
+    
+    def list_tasks(
+        self,
+        subpath: str = "",
+        recursive: bool = True,
+        include_content: bool = False,
+        project: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """
+        List all tasks in a directory
+        
+        Args:
+            subpath: Subdirectory within project or a project name when `project` is omitted
+            recursive: Include subdirectories
+            include_content: Include full content in results (token-expensive)
+            project: Optional project name to scope the listing
+        
+        Returns:
+            List of task dictionaries
+        """
+        # Resolve search path based on project and subpath
+        if subpath:
+            sp = Path(subpath)
+            if project is None:
+                # If subpath looks like 'project/...' or a single project name, take it as the project
+                if len(sp.parts) >= 2:
+                    project = sp.parts[0]
+                    sub = Path(*sp.parts[1:])
+                else:
+                    project = sp.parts[0]
+                    sub = Path()
+            else:
+                sub = Path(subpath)
+        else:
+            sub = Path()
+
+        if project is None:
+            search_path = self.base_path
+        else:
+            search_path = self.base_path / project / sub
+
+        if not search_path.exists():
+            return []
+
+        pattern = "**/*.md" if recursive else "*.md"
+        tasks = []
+
+        for md_file in search_path.glob(pattern):
+            try:
+                with open(md_file, 'r', encoding='utf-8') as f:
+                    post = frontmatter.load(f)
+
+                task_info = {
+                    'path': md_file.relative_to(self.base_path).as_posix(),
+                    'title': post.get('title', ''),
+                    'metadata': post.metadata
+                }
+
+                if include_content:
+                    task_info['content'] = post.content
+
+                tasks.append(task_info)
+            except Exception as e:
+                # Skip files that can't be parsed
+                continue
+
+        return tasks
+    
+    def get_structure(self, subpath: str = "", project: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Get the hierarchical structure of tasks
+        
+        Args:
+            subpath: Subdirectory within base_path or a project/subpath when `project` is omitted
+            project: Optional project name to scope the structure
+        
+        Returns:
+            Nested dictionary representing folder structure
+        """
+        # Resolve search path similarly to `list_tasks` to support the same CLI semantics
+        if subpath:
+            sp = Path(subpath)
+            if project is None:
+                # If subpath looks like 'project/...' or a single project name, take it as the project
+                if len(sp.parts) >= 2:
+                    project = sp.parts[0]
+                    sub = Path(*sp.parts[1:])
+                else:
+                    project = sp.parts[0]
+                    sub = Path()
+            else:
+                sub = Path(subpath)
+        else:
+            sub = Path()
+
+        # Validate relative path usage
+        if any(part == ".." for part in sub.parts):
+            raise ValueError("path must not contain parent references")
+
+        if project is None:
+            search_path = self.base_path
+        else:
+            search_path = self.base_path / project / sub
+
+        if project is not None and not search_path.exists():
+            # Signal a project resolution failure to callers (CLI / MCP handlers expect ValueError)
+            raise ValueError(f"project '{project}' not found")
+
+        def build_tree(path: Path) -> Dict[str, Any]:
+            tree = {
+                'type': 'directory',
+                'name': path.name or 'root',
+                'children': []
+            }
+            
+            try:
+                for item in sorted(path.iterdir()):
+                    if item.is_dir():
+                        tree['children'].append(build_tree(item))
+                    elif item.suffix == '.md':
+                        try:
+                            with open(item, 'r', encoding='utf-8') as f:
+                                post = frontmatter.load(f)
+                            
+                            tree['children'].append({
+                                'type': 'task',
+                                'name': item.name,
+                                'path': item.relative_to(self.base_path).as_posix(),
+                                'title': post.get('title', ''),
+                                'metadata': {k: v for k, v in post.metadata.items() 
+                                           if k in ['status', 'priority', 'tags']}
+                            })
+                        except Exception:
+                            continue
+            except Exception:
+                pass
+            
+            return tree
+        
+        return build_tree(search_path)
+    
+    def move_task(self, old_path: str, new_path: str, project: Optional[str] = None) -> bool:
+        """
+        Move/rename a task card
+        
+        Args:
+            old_path: Current relative path within project or with project prefix
+            new_path: New relative path within project or with project prefix
+            project: Optional project name to scope the move (applies to both paths if provided)
+        
+        Returns:
+            True if moved, False if source not found or destination exists
+        """
+        old_full, old_rel = self._resolve_path(project, old_path)
+        new_full, new_rel = self._resolve_path(project, new_path)
+        
+        if not old_full.exists() or new_full.exists():
+            return False
+        
+        new_full.parent.mkdir(parents=True, exist_ok=True)
+        old_full.rename(new_full)
+        
+        # Clean up empty parent directories
+        try:
+            parent = old_full.parent
+            while parent != self.base_path and not any(parent.iterdir()):
+                parent.rmdir()
+                parent = parent.parent
+        except Exception:
+            pass
+        
+        return True

taskmaster/utils.py

@@ -0,0 +1,12 @@
+"""
+Utilities for TaskMaster shared by CLI and MCP adapters
+"""
+from typing import Any
+
+
+def project_resolution_error_msg(exc: Exception) -> str:
+    """Format a consistent user-facing error message when project resolution fails.
+
+    Returns a short sentence that suggests remedies (use `--project` or prefix the path).
+    """
+    return f"✗ {exc}. Provide a project with `--project <name>` or prefix the path with 'project/'."