kestrel-feature-github 0.1.0__py3-none-any.whl

kestrel_feature_github/SKILL.md

@@ -0,0 +1,101 @@
+# GitHubFeature
+
+> GitHub integration for issues, PRs, repository access, and code introspection.
+
+## Skills
+
+### read_github_file
+- **Description**: Read a file from a GitHub repository
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, required): Repository in 'owner/repo' format, or 'self'
+  - `path` (string, required): Path to file within the repository
+  - `ref` (string, optional): Branch, tag, or commit SHA (default: main)
+
+### list_github_files
+- **Description**: List files in a GitHub repository directory
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, required): Repository in 'owner/repo' format, or 'self'
+  - `path` (string, optional): Directory path (empty for root)
+  - `ref` (string, optional): Branch, tag, or commit SHA
+  - `recursive` (boolean, optional): If true, list all files recursively
+
+### search_github_code
+- **Description**: Search for code in GitHub repositories
+- **Category**: data_access
+- **Parameters**:
+  - `query` (string, required): Search query
+  - `repo` (string, optional): Limit to specific repo
+  - `path` (string, optional): Limit to path prefix
+  - `extension` (string, optional): Limit to file extension
+  - `max_results` (integer, optional): Maximum results (default 20)
+
+### get_code_definition
+- **Description**: Get a function or class definition from a Python file using AST
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, required): Repository or 'self'
+  - `path` (string, required): Path to Python file
+  - `name` (string, required): Function or class name
+  - `ref` (string, optional): Branch, tag, or commit SHA
+
+### list_code_definitions
+- **Description**: List all functions and classes in a Python file
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, required): Repository or 'self'
+  - `path` (string, required): Path to Python file
+  - `ref` (string, optional): Branch, tag, or commit SHA
+
+### get_self_repo_info
+- **Description**: Get information about the agent's own source repository
+- **Category**: data_access
+
+### list_source_components
+- **Description**: List all feature components in the agent's source code
+- **Category**: data_access
+- **Parameters**:
+  - `include_files` (boolean, optional): Include file listings for each component
+
+### get_component_source
+- **Description**: Get all source files for a specific feature component
+- **Category**: data_access
+- **Parameters**:
+  - `component` (string, required): Component name
+  - `include_content` (boolean, optional): Include file contents
+
+### invalidate_github_cache
+- **Description**: Invalidate cached GitHub content to force fresh fetch
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, required): Repository to invalidate (or 'self')
+  - `path` (string, optional): Specific path to invalidate
+
+### list_github_issues
+- **Description**: List issues in a GitHub repository
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, optional): Repository or 'self' (default: self)
+  - `state` (string, optional): Issue state filter (default: open)
+  - `labels` (string, optional): Comma-separated label names
+  - `max_results` (integer, optional): Maximum results (default 30)
+
+### get_github_issue
+- **Description**: Get details of a specific GitHub issue
+- **Category**: data_access
+- **Parameters**:
+  - `issue_number` (integer, required): Issue number
+  - `repo` (string, optional): Repository or 'self' (default: self)
+
+### get_github_issue_comments
+- **Description**: Get comments on a specific GitHub issue
+- **Category**: data_access
+- **Parameters**:
+  - `issue_number` (integer, required): Issue number
+  - `repo` (string, optional): Repository or 'self' (default: self)
+  - `max_results` (integer, optional): Maximum comments (default 30)
+
+## Dependencies
+
+- Requires: kestrel-sovereign, httpx, pyyaml, aiosqlite

kestrel_feature_github/__init__.py

@@ -0,0 +1,4 @@
+"""Kestrel Feature: GitHub integration for issues, PRs, and repository management."""
+from .feature import GitHubFeature
+
+__all__ = ["GitHubFeature"]

kestrel_feature_github/ast_analyzer.py

@@ -0,0 +1,261 @@
+"""AST-based code analysis for Python files."""
+import ast
+import logging
+from typing import Optional
+
+from .models import CodeDefinition
+
+logger = logging.getLogger(__name__)
+
+
+class ASTAnalyzer:
+    """Extract code definitions from Python source using AST."""
+
+    def __init__(self, source: str, path: str = ""):
+        """Initialize with source code.
+
+        Args:
+            source: Python source code
+            path: File path for error messages
+        """
+        self.source = source
+        self.path = path
+        self.lines = source.splitlines()
+        self._tree: Optional[ast.AST] = None
+
+    def parse(self) -> bool:
+        """Parse source into AST.
+
+        Returns:
+            True if parsing succeeded
+        """
+        try:
+            self._tree = ast.parse(self.source, filename=self.path)
+            return True
+        except SyntaxError as e:
+            logger.warning(f"Failed to parse {self.path}: {e}")
+            return False
+
+    def get_definitions(self) -> list[CodeDefinition]:
+        """Extract all function and class definitions.
+
+        Returns:
+            List of code definitions
+        """
+        if self._tree is None:
+            if not self.parse():
+                return []
+
+        definitions = []
+
+        for node in ast.walk(self._tree):
+            if isinstance(node, ast.FunctionDef):
+                definitions.append(self._extract_function(node))
+            elif isinstance(node, ast.AsyncFunctionDef):
+                definitions.append(self._extract_function(node, is_async=True))
+            elif isinstance(node, ast.ClassDef):
+                definitions.append(self._extract_class(node))
+
+        return definitions
+
+    def get_definition(self, name: str) -> Optional[CodeDefinition]:
+        """Get a specific definition by name.
+
+        Args:
+            name: Function or class name
+
+        Returns:
+            CodeDefinition if found
+        """
+        for defn in self.get_definitions():
+            if defn.name == name:
+                return defn
+        return None
+
+    def get_imports(self) -> list[dict]:
+        """Extract import statements.
+
+        Returns:
+            List of import info dicts
+        """
+        if self._tree is None:
+            if not self.parse():
+                return []
+
+        imports = []
+
+        for node in ast.walk(self._tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imports.append({
+                        "type": "import",
+                        "module": alias.name,
+                        "alias": alias.asname,
+                        "line": node.lineno,
+                    })
+            elif isinstance(node, ast.ImportFrom):
+                module = node.module or ""
+                for alias in node.names:
+                    imports.append({
+                        "type": "from",
+                        "module": module,
+                        "name": alias.name,
+                        "alias": alias.asname,
+                        "line": node.lineno,
+                        "level": node.level,
+                    })
+
+        return imports
+
+    def _extract_function(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        is_async: bool = False,
+    ) -> CodeDefinition:
+        """Extract function definition."""
+        # Get signature
+        args = self._format_arguments(node.args)
+        returns = ""
+        if node.returns:
+            returns = f" -> {ast.unparse(node.returns)}"
+
+        prefix = "async def" if is_async else "def"
+        signature = f"{prefix} {node.name}({args}){returns}"
+
+        # Get docstring
+        docstring = ast.get_docstring(node) or ""
+
+        # Get source lines
+        end_line = self._find_end_line(node)
+        source = "\n".join(self.lines[node.lineno - 1:end_line])
+
+        # Determine type
+        def_type = "method" if self._is_method(node) else "function"
+
+        return CodeDefinition(
+            name=node.name,
+            type=def_type,
+            path=self.path,
+            start_line=node.lineno,
+            end_line=end_line,
+            signature=signature,
+            docstring=docstring,
+            source=source,
+        )
+
+    def _extract_class(self, node: ast.ClassDef) -> CodeDefinition:
+        """Extract class definition."""
+        # Get bases
+        bases = ", ".join(ast.unparse(base) for base in node.bases)
+        signature = f"class {node.name}({bases})" if bases else f"class {node.name}"
+
+        # Get docstring
+        docstring = ast.get_docstring(node) or ""
+
+        # Get source lines
+        end_line = self._find_end_line(node)
+        source = "\n".join(self.lines[node.lineno - 1:end_line])
+
+        return CodeDefinition(
+            name=node.name,
+            type="class",
+            path=self.path,
+            start_line=node.lineno,
+            end_line=end_line,
+            signature=signature,
+            docstring=docstring,
+            source=source,
+        )
+
+    def _format_arguments(self, args: ast.arguments) -> str:
+        """Format function arguments."""
+        parts = []
+
+        # Regular args
+        defaults_start = len(args.args) - len(args.defaults)
+        for i, arg in enumerate(args.args):
+            arg_str = arg.arg
+            if arg.annotation:
+                arg_str += f": {ast.unparse(arg.annotation)}"
+
+            default_idx = i - defaults_start
+            if default_idx >= 0:
+                arg_str += f" = {ast.unparse(args.defaults[default_idx])}"
+
+            parts.append(arg_str)
+
+        # *args
+        if args.vararg:
+            arg_str = f"*{args.vararg.arg}"
+            if args.vararg.annotation:
+                arg_str += f": {ast.unparse(args.vararg.annotation)}"
+            parts.append(arg_str)
+        elif args.kwonlyargs:
+            parts.append("*")
+
+        # Keyword-only args
+        for i, arg in enumerate(args.kwonlyargs):
+            arg_str = arg.arg
+            if arg.annotation:
+                arg_str += f": {ast.unparse(arg.annotation)}"
+            if args.kw_defaults[i]:
+                arg_str += f" = {ast.unparse(args.kw_defaults[i])}"
+            parts.append(arg_str)
+
+        # **kwargs
+        if args.kwarg:
+            arg_str = f"**{args.kwarg.arg}"
+            if args.kwarg.annotation:
+                arg_str += f": {ast.unparse(args.kwarg.annotation)}"
+            parts.append(arg_str)
+
+        return ", ".join(parts)
+
+    def _find_end_line(self, node: ast.AST) -> int:
+        """Find the last line of a node."""
+        end_line = node.lineno
+
+        for child in ast.walk(node):
+            if hasattr(child, "lineno"):
+                end_line = max(end_line, child.lineno)
+            if hasattr(child, "end_lineno") and child.end_lineno:
+                end_line = max(end_line, child.end_lineno)
+
+        return end_line
+
+    def _is_method(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+        """Check if function is a method (inside a class)."""
+        # Check if first argument is self or cls
+        if node.args.args:
+            first_arg = node.args.args[0].arg
+            return first_arg in ("self", "cls")
+        return False
+
+
+def extract_definition(source: str, name: str, path: str = "") -> Optional[CodeDefinition]:
+    """Convenience function to extract a single definition.
+
+    Args:
+        source: Python source code
+        name: Name to find
+        path: File path for context
+
+    Returns:
+        CodeDefinition if found
+    """
+    analyzer = ASTAnalyzer(source, path)
+    return analyzer.get_definition(name)
+
+
+def list_definitions(source: str, path: str = "") -> list[CodeDefinition]:
+    """Convenience function to list all definitions.
+
+    Args:
+        source: Python source code
+        path: File path for context
+
+    Returns:
+        List of all definitions
+    """
+    analyzer = ASTAnalyzer(source, path)
+    return analyzer.get_definitions()

kestrel_feature_github/cache.py

@@ -0,0 +1,288 @@
+"""SQLite cache for GitHub content."""
+import json
+import logging
+import os
+import aiosqlite
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+from .models import FileContent
+
+logger = logging.getLogger(__name__)
+
+
+class GitHubCache:
+    """Async SQLite-backed cache for GitHub file content."""
+
+    DEFAULT_TTL = timedelta(hours=1)
+
+    def __init__(self, db_path: Optional[str] = None):
+        """Initialize cache.
+
+        Args:
+            db_path: Path to SQLite database. Defaults to KESTREL_DB_PATH/github_cache.db
+        """
+        if db_path is None:
+            base_path = os.getenv("KESTREL_DB_PATH", "./agent_data")
+            db_path = os.path.join(base_path, "github_cache.db")
+
+        self.db_path = db_path
+        Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+        self._initialized = False
+
+    async def _ensure_initialized(self):
+        """Initialize database schema if not already done."""
+        if self._initialized:
+            return
+
+        async with aiosqlite.connect(self.db_path) as conn:
+            await conn.execute("""
+                CREATE TABLE IF NOT EXISTS file_cache (
+                    cache_key TEXT PRIMARY KEY,
+                    repo TEXT NOT NULL,
+                    path TEXT NOT NULL,
+                    ref TEXT NOT NULL,
+                    content TEXT NOT NULL,
+                    sha TEXT NOT NULL,
+                    size INTEGER NOT NULL,
+                    cached_at TEXT NOT NULL,
+                    expires_at TEXT NOT NULL
+                )
+            """)
+            await conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_file_cache_repo
+                ON file_cache(repo, path)
+            """)
+            await conn.execute("""
+                CREATE TABLE IF NOT EXISTS tree_cache (
+                    cache_key TEXT PRIMARY KEY,
+                    repo TEXT NOT NULL,
+                    ref TEXT NOT NULL,
+                    tree_json TEXT NOT NULL,
+                    cached_at TEXT NOT NULL,
+                    expires_at TEXT NOT NULL
+                )
+            """)
+            await conn.commit()
+        self._initialized = True
+
+    def _make_key(self, repo: str, path: str, ref: str) -> str:
+        """Create cache key."""
+        return f"{repo}:{ref}:{path}"
+
+    async def get(self, repo: str, path: str, ref: str = "main") -> Optional[FileContent]:
+        """Get file from cache if not expired.
+
+        Args:
+            repo: Repository in 'owner/repo' format
+            path: Path to file
+            ref: Branch, tag, or SHA
+
+        Returns:
+            FileContent if cached and not expired, else None
+        """
+        await self._ensure_initialized()
+        key = self._make_key(repo, path, ref)
+        now = datetime.now(timezone.utc).isoformat()
+
+        async with aiosqlite.connect(self.db_path) as conn:
+            cursor = await conn.execute(
+                """
+                SELECT content, sha, size, cached_at
+                FROM file_cache
+                WHERE cache_key = ? AND expires_at > ?
+                """,
+                (key, now),
+            )
+            row = await cursor.fetchone()
+
+            if row:
+                return FileContent(
+                    path=path,
+                    content=row[0],
+                    sha=row[1],
+                    size=row[2],
+                    repo=repo,
+                    ref=ref,
+                    cached_at=datetime.fromisoformat(row[3]),
+                )
+
+        return None
+
+    async def set(
+        self,
+        file_content: FileContent,
+        ttl: Optional[timedelta] = None,
+    ):
+        """Cache file content.
+
+        Args:
+            file_content: Content to cache
+            ttl: Time to live, defaults to 1 hour
+        """
+        await self._ensure_initialized()
+        if ttl is None:
+            ttl = self.DEFAULT_TTL
+
+        key = self._make_key(file_content.repo, file_content.path, file_content.ref)
+        now = datetime.now(timezone.utc)
+        expires = now + ttl
+
+        async with aiosqlite.connect(self.db_path) as conn:
+            await conn.execute(
+                """
+                INSERT OR REPLACE INTO file_cache
+                (cache_key, repo, path, ref, content, sha, size, cached_at, expires_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    key,
+                    file_content.repo,
+                    file_content.path,
+                    file_content.ref,
+                    file_content.content,
+                    file_content.sha,
+                    file_content.size,
+                    now.isoformat(),
+                    expires.isoformat(),
+                ),
+            )
+            await conn.commit()
+
+    async def get_tree(self, repo: str, ref: str = "main") -> Optional[list[dict]]:
+        """Get cached repository tree.
+
+        Args:
+            repo: Repository in 'owner/repo' format
+            ref: Branch, tag, or SHA
+
+        Returns:
+            List of tree entries if cached, else None
+        """
+        await self._ensure_initialized()
+        key = f"{repo}:{ref}:tree"
+        now = datetime.now(timezone.utc).isoformat()
+
+        async with aiosqlite.connect(self.db_path) as conn:
+            cursor = await conn.execute(
+                """
+                SELECT tree_json FROM tree_cache
+                WHERE cache_key = ? AND expires_at > ?
+                """,
+                (key, now),
+            )
+            row = await cursor.fetchone()
+
+            if row:
+                return json.loads(row[0])
+
+        return None
+
+    async def set_tree(
+        self,
+        repo: str,
+        ref: str,
+        tree: list[dict],
+        ttl: Optional[timedelta] = None,
+    ):
+        """Cache repository tree.
+
+        Args:
+            repo: Repository in 'owner/repo' format
+            ref: Branch, tag, or SHA
+            tree: Tree entries to cache
+            ttl: Time to live
+        """
+        await self._ensure_initialized()
+        if ttl is None:
+            ttl = self.DEFAULT_TTL
+
+        key = f"{repo}:{ref}:tree"
+        now = datetime.now(timezone.utc)
+        expires = now + ttl
+
+        async with aiosqlite.connect(self.db_path) as conn:
+            await conn.execute(
+                """
+                INSERT OR REPLACE INTO tree_cache
+                (cache_key, repo, ref, tree_json, cached_at, expires_at)
+                VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                (key, repo, ref, json.dumps(tree), now.isoformat(), expires.isoformat()),
+            )
+            await conn.commit()
+
+    async def invalidate(self, repo: str, path: Optional[str] = None, ref: Optional[str] = None):
+        """Invalidate cache entries.
+
+        Args:
+            repo: Repository to invalidate
+            path: Specific path to invalidate (optional)
+            ref: Specific ref to invalidate (optional)
+        """
+        await self._ensure_initialized()
+        async with aiosqlite.connect(self.db_path) as conn:
+            if path and ref:
+                key = self._make_key(repo, path, ref)
+                await conn.execute("DELETE FROM file_cache WHERE cache_key = ?", (key,))
+            elif ref:
+                await conn.execute(
+                    "DELETE FROM file_cache WHERE repo = ? AND ref = ?",
+                    (repo, ref),
+                )
+                await conn.execute(
+                    "DELETE FROM tree_cache WHERE repo = ? AND ref = ?",
+                    (repo, ref),
+                )
+            else:
+                await conn.execute("DELETE FROM file_cache WHERE repo = ?", (repo,))
+                await conn.execute("DELETE FROM tree_cache WHERE repo = ?", (repo,))
+            await conn.commit()
+
+    async def clear_expired(self):
+        """Remove all expired cache entries."""
+        await self._ensure_initialized()
+        now = datetime.now(timezone.utc).isoformat()
+
+        async with aiosqlite.connect(self.db_path) as conn:
+            await conn.execute("DELETE FROM file_cache WHERE expires_at < ?", (now,))
+            await conn.execute("DELETE FROM tree_cache WHERE expires_at < ?", (now,))
+            await conn.commit()
+
+    async def stats(self) -> dict:
+        """Get cache statistics.
+
+        Returns:
+            Dict with cache stats
+        """
+        await self._ensure_initialized()
+        now = datetime.now(timezone.utc).isoformat()
+
+        async with aiosqlite.connect(self.db_path) as conn:
+            cursor = await conn.execute(
+                "SELECT COUNT(*) FROM file_cache WHERE expires_at > ?", (now,)
+            )
+            file_count = (await cursor.fetchone())[0]
+
+            cursor = await conn.execute(
+                "SELECT COUNT(*) FROM tree_cache WHERE expires_at > ?", (now,)
+            )
+            tree_count = (await cursor.fetchone())[0]
+
+            cursor = await conn.execute(
+                "SELECT COALESCE(SUM(size), 0) FROM file_cache WHERE expires_at > ?", (now,)
+            )
+            total_size = (await cursor.fetchone())[0]
+
+            cursor = await conn.execute(
+                "SELECT DISTINCT repo FROM file_cache WHERE expires_at > ?", (now,)
+            )
+            repos = await cursor.fetchall()
+
+        return {
+            "cached_files": file_count,
+            "cached_trees": tree_count,
+            "total_size_bytes": total_size,
+            "repos": [r[0] for r in repos],
+        }