wicked-garden 12.27.0

package/scripts/smaht/adapters/brain_adapter.py

@@ -0,0 +1,254 @@
+"""
+Brain adapter for wicked-smaht context assembly.
+
+Queries the wicked-brain FTS5 index for code and document context
+relevant to the current prompt. Returns ContextItems tagged with
+source="brain" so the slow path briefing formatter labels them correctly.
+
+wicked-brain is a required dependency — context assembly is degraded without it.
+When brain is unreachable, this adapter logs a warning to stderr and returns empty.
+"""
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import List
+
+from . import ContextItem, run_in_thread
+
+_STOP_WORDS = frozenset({
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "have", "has",
+    "had", "do", "does", "did", "will", "would", "could", "should", "can",
+    "may", "might", "must", "i", "you", "we", "they", "me", "my", "your",
+    "this", "that", "these", "those", "what", "which", "who", "how", "why",
+    "when", "where", "and", "or", "but", "if", "for", "of", "to", "from",
+    "in", "on", "at", "by", "with", "about", "not", "so", "just", "also",
+    "need", "want", "let", "get", "make", "test", "check", "fix", "work",
+    # English filler that passes len>2 but over-constrains FTS5 AND matching
+    "one", "two", "all", "any", "some", "out", "use", "via", "per",
+    "without", "going", "through", "using", "into", "onto", "upon",
+    "there", "their", "then", "than", "its", "our", "has",
+    # Prepositions / general connectors that look content-y but aren't
+    "between", "across", "along", "around", "before", "after",
+    "exist", "exists", "show", "tell", "give", "take",
+})
+
+
+def _extract_keywords(prompt: str, limit: int = 3) -> str:
+    """Extract up to `limit` keywords for FTS5 AND query.
+
+    Position-order preserves the prompt's intent; the first non-stop words
+    are almost always the topic. Callers pass limit=2 for retry fallback.
+    """
+    words = prompt.lower().split()
+    keywords = [w for w in words if w not in _STOP_WORDS and len(w) > 2]
+    seen: set[str] = set()
+    unique = []
+    for w in keywords:
+        if w not in seen:
+            seen.add(w)
+            unique.append(w)
+    return " ".join(unique[:limit]) if unique else ""
+
+
+def _query_brain(prompt: str) -> list:
+    """Query brain FTS5 index with automatic recall fallback.
+
+    FTS5 uses AND — more terms = fewer results. Try 3 terms first (higher
+    precision); if < 2 results, try two 2-term combinations and pick the
+    one with more results:
+      - first + third (drop middle — often the most generic term)
+      - first + second (standard narrowing)
+    """
+    keywords = _extract_keywords(prompt, limit=3).split()
+    if not keywords:
+        return []
+
+    query = " ".join(keywords)
+
+    try:
+        from _brain_port import resolve_port as _resolve_port
+        port = _resolve_port()
+
+        def _search(q: str) -> list:
+            payload = json.dumps({
+                "action": "search",
+                "params": {"query": q, "limit": 10},
+            }).encode("utf-8")
+            req = urllib.request.Request(
+                f"http://localhost:{port}/api",
+                data=payload,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=3) as resp:
+                return json.loads(resp.read().decode("utf-8")).get("results", [])
+
+        results = _search(query)
+        if len(results) < 2 and len(keywords) >= 3:
+            # Try dropping the middle keyword (often the least specific)
+            alt_a = f"{keywords[0]} {keywords[2]}"  # first + third
+            alt_b = f"{keywords[0]} {keywords[1]}"  # first + second
+            ra = _search(alt_a)
+            rb = _search(alt_b)
+            # Prefer whichever returns more results (wider recall)
+            results = ra if len(ra) >= len(rb) else rb
+        elif len(results) < 2 and len(keywords) == 2:
+            # Already at 2 terms; nothing further to try
+            pass  # intentional: no-op
+        return results
+    except Exception as _e:
+        print(
+            f"smaht: brain adapter unreachable (port {port})"
+            f" — context assembly degraded: {type(_e).__name__}",
+            file=sys.stderr,
+        )
+        return []
+
+
+def _keyword_score(prompt_lower: str, text: str) -> float:
+    """Score text by keyword overlap with prompt."""
+    if not text:
+        return 0.0
+    text_lower = text.lower()
+    score = 0.0
+    for word in prompt_lower.split():
+        if len(word) > 3 and word in text_lower:
+            score += 0.15
+    return min(score, 0.45)
+
+
+def _readable_title(source_file: str) -> str:
+    """Convert a chunk source path to a human-readable title.
+
+    e.g. "skills-crew-workflow-refs-specialist-routing-rules.md"
+      → "crew / specialist-routing-rules"
+    """
+    import re as _re
+    # Strip leading domain prefix like "skills-", "commands-", "agents-", "hooks-"
+    name = _re.sub(r'^(skills|commands|agents|hooks|scenarios|scripts|docs)-', '', source_file)
+    # Strip .md extension
+    name = name.removesuffix('.md')
+    # Split on '-' to get components; find the domain and the tail
+    parts = name.split('-')
+    if len(parts) >= 2:
+        # First part is domain; rest is description
+        domain = parts[0]
+        # Skip "refs" and numeric-looking chunks
+        desc_parts = [p for p in parts[1:] if p != 'refs' and not p.startswith('chunk')]
+        if desc_parts:
+            return f"{domain} / {'-'.join(desc_parts)}"
+    return name
+
+
+def _clean_snippet(raw: str) -> str:
+    """Strip YAML frontmatter lines and FTS highlight tags from snippet.
+
+    FTS5 snippets contain frontmatter when the brain server re-indexes full
+    chunk files. Strip aggressively: snake_case keys, floats, timestamps,
+    list tags, and separator markers.
+    """
+    import re as _re
+
+    # Remove FTS5 highlight markers and ellipsis separators
+    text = _re.sub(r"<[^>]+>", "", raw)
+    text = text.replace("…", " ").replace("...", " ")
+
+    # Patterns that indicate frontmatter / metadata noise — skip these lines
+    _yaml_key   = _re.compile(r'^[a-z][a-z_]+:\s*')        # snake_case key: value
+    _bare_float = _re.compile(r'^\d+\.\d+$')               # e.g. "0.7"
+    _timestamp  = _re.compile(r'^\d{4}-\d{2}-\d{2}')       # ISO date
+    _tag_list   = _re.compile(r'^- [a-z][\w\-]*$')         # bare YAML tag list items
+    _flag_list  = _re.compile(r'^- --[\w\-]+')             # CLI flag list items: - --flag
+    _uuid_like  = _re.compile(r'^[a-f0-9\-]{8,}$')         # UUIDs
+    # Leftover path values after their YAML key was stripped
+    _file_path  = _re.compile(r'^[\w/.\- ]+\.(md|py|js|ts|jsx|tsx|json|yaml|yml|sh|txt)$')
+    # chunk-ID paths: "source-name/chunk-NNN" or bare "chunk-NNN"
+    _chunk_id   = _re.compile(r'(^|/)chunk-\d+')
+    # Markdown table rows: any line starting with | (data rows and separators)
+    _table_row  = _re.compile(r'^\|')
+
+    lines = []
+    for line in text.split("\n"):
+        stripped = line.strip()
+        if not stripped or stripped == "---":
+            continue
+        if (_yaml_key.match(stripped)
+                or _bare_float.match(stripped)
+                or _timestamp.match(stripped)
+                or _tag_list.match(stripped)
+                or _flag_list.match(stripped)
+                or _uuid_like.match(stripped)
+                or _file_path.match(stripped)
+                or _chunk_id.search(stripped)
+                or _table_row.match(stripped)):
+            continue
+        lines.append(stripped)
+
+    result = " ".join(lines).strip()
+    return result[:160] if result else ""
+
+
+async def query(prompt: str) -> List[ContextItem]:
+    """Query brain for code and document context relevant to the prompt."""
+    results = await run_in_thread(_query_brain, prompt)
+    if not results:
+        return []
+
+    import re
+    # Score against extracted keywords only (not full prompt) so incidental
+    # words in the prompt (e.g. "crew" in "without going through the crew
+    # workflow") don't boost unrelated documents that happen to mention them.
+    score_against = _extract_keywords(prompt, limit=3) or prompt.lower()
+
+    # First pass: build items grouped by source file (deduplicate chunks → 1 item per source)
+    best_by_source: dict[str, dict] = {}
+
+    for r in results:
+        path = r.get("path", "") or r.get("id", "")
+        snippet = r.get("snippet", "")
+
+        # Determine source file from chunk path
+        source_file = ""
+        if "chunks/extracted/" in path:
+            part = path.replace("chunks/extracted/", "").split("/chunk-")[0]
+            source_file = part
+        else:
+            source_file = path
+
+        clean_snippet = _clean_snippet(snippet)
+        kw_score = _keyword_score(score_against, f"{source_file} {clean_snippet}")
+        # Items with no readable snippet get a relevance floor of 0.2 so they
+        # rank below items that survived cleaning and only appear if budget allows.
+        base = 0.2 if not clean_snippet else 0.3
+        relevance = min(base + kw_score, 1.0)
+
+        # Keep only the highest-scoring chunk per source file
+        existing = best_by_source.get(source_file)
+        if existing is None or relevance > existing["relevance"]:
+            best_by_source[source_file] = {
+                "path": path,
+                "source_file": source_file,
+                "snippet": clean_snippet,
+                "relevance": relevance,
+            }
+
+    # Second pass: convert to ContextItems
+    items: List[ContextItem] = []
+    for source_file, entry in best_by_source.items():
+        title = _readable_title(source_file)
+        items.append(ContextItem(
+            id=entry["path"],
+            source="brain",
+            title=title,
+            summary=entry["snippet"],
+            excerpt=entry["snippet"][:100],
+            relevance=entry["relevance"],
+            metadata={"brain_path": entry["path"]},
+        ))
+
+    items.sort(key=lambda x: x.relevance, reverse=True)
+    return items

package/scripts/smaht/adapters/context7_adapter.py

@@ -0,0 +1,438 @@
+"""
+wicked-smaht adapter for Context7.
+
+Queries external library documentation via Context7 MCP integration.
+Provides graceful degradation when Context7 is unavailable.
+"""
+
+import asyncio
+import hashlib
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+
+from . import ContextItem, _SCRIPTS_ROOT
+
+if str(_SCRIPTS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_ROOT))
+
+from _domain_store import get_local_path
+
+
+# Cache configuration
+CACHE_DIR = get_local_path("wicked-smaht", "cache", "context7")
+CACHE_TTL_SECONDS = 3600  # 1 hour
+MAX_CACHE_ENTRIES = 500
+
+
+class Context7Cache:
+    """Simple file-based cache for Context7 query results."""
+
+    def __init__(self, cache_dir: Path = CACHE_DIR):
+        self.cache_dir = cache_dir
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.index_path = cache_dir / "index.json"
+        self.data_dir = cache_dir / "data"
+        self.data_dir.mkdir(exist_ok=True)
+        self._load_index()
+
+    def _load_index(self):
+        """Load cache index from disk."""
+        if self.index_path.exists():
+            try:
+                with open(self.index_path) as f:
+                    self.index = json.load(f)
+            except Exception:
+                self.index = {}
+        else:
+            self.index = {}
+
+    def _save_index(self):
+        """Save cache index to disk."""
+        with open(self.index_path, 'w') as f:
+            json.dump(self.index, f, indent=2)
+
+    def _cache_key(self, library_id: str, query: str) -> str:
+        """Generate cache key from library ID and query."""
+        content = f"{library_id}:{query}"
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+    def _is_valid(self, entry: Dict[str, Any]) -> bool:
+        """Check if cache entry is still valid."""
+        cached_at = datetime.fromisoformat(entry['cached_at'])
+        age_seconds = (datetime.now(timezone.utc) - cached_at).total_seconds()
+        return age_seconds < CACHE_TTL_SECONDS
+
+    def get(self, library_id: str, query: str) -> Optional[List[ContextItem]]:
+        """Get cached results if valid, None otherwise."""
+        key = self._cache_key(library_id, query)
+
+        # Check index
+        if key not in self.index:
+            return None
+
+        entry = self.index[key]
+
+        # Validate TTL
+        if not self._is_valid(entry):
+            # Clean up expired entry
+            self._remove(key)
+            return None
+
+        # Load data
+        data_path = self.data_dir / f"{key}.json"
+        if not data_path.exists():
+            # Index/data mismatch - clean up
+            self._remove(key)
+            return None
+
+        try:
+            with open(data_path) as f:
+                data = json.load(f)
+
+            # Reconstruct ContextItems
+            items = []
+            for item_data in data:
+                items.append(ContextItem(
+                    id=item_data['id'],
+                    source=item_data['source'],
+                    title=item_data['title'],
+                    summary=item_data['summary'],
+                    excerpt=item_data.get('excerpt', ''),
+                    relevance=item_data.get('relevance', 0.0),
+                    age_days=item_data.get('age_days', 0.0),
+                    metadata=item_data.get('metadata', {})
+                ))
+
+            return items
+        except Exception as e:
+            print(f"Warning: Failed to load cache entry {key}: {e}", file=sys.stderr)
+            self._remove(key)
+            return None
+
+    def set(self, library_id: str, query: str, items: List[ContextItem]):
+        """Cache query results."""
+        key = self._cache_key(library_id, query)
+
+        # Serialize items
+        items_data = []
+        for item in items:
+            items_data.append({
+                'id': item.id,
+                'source': item.source,
+                'title': item.title,
+                'summary': item.summary,
+                'excerpt': item.excerpt,
+                'relevance': item.relevance,
+                'age_days': item.age_days,
+                'metadata': item.metadata
+            })
+
+        # Write data
+        data_path = self.data_dir / f"{key}.json"
+        with open(data_path, 'w') as f:
+            json.dump(items_data, f, indent=2)
+
+        # Update index
+        self.index[key] = {
+            'library_id': library_id,
+            'query': query,
+            'cached_at': datetime.now(timezone.utc).isoformat(),
+            'item_count': len(items)
+        }
+
+        # Enforce max entries (LRU-style cleanup)
+        if len(self.index) > MAX_CACHE_ENTRIES:
+            self._evict_oldest()
+
+        self._save_index()
+
+    def _remove(self, key: str):
+        """Remove cache entry."""
+        # Remove from index
+        if key in self.index:
+            del self.index[key]
+            self._save_index()
+
+        # Remove data file
+        data_path = self.data_dir / f"{key}.json"
+        if data_path.exists():
+            data_path.unlink()
+
+    def _evict_oldest(self):
+        """Evict oldest 10% of entries."""
+        # Sort by cached_at
+        sorted_entries = sorted(
+            self.index.items(),
+            key=lambda x: x[1]['cached_at']
+        )
+
+        evict_count = max(1, len(sorted_entries) // 10)
+        for key, _ in sorted_entries[:evict_count]:
+            self._remove(key)
+
+    def clear(self):
+        """Clear entire cache."""
+        for key in list(self.index.keys()):
+            self._remove(key)
+
+
+# Global cache instance
+_cache = Context7Cache()
+
+
+async def query(prompt: str, project: str = None) -> List[ContextItem]:
+    """
+    Query Context7 for relevant library documentation.
+
+    This adapter uses the Context7 MCP integration to fetch external library docs.
+
+    Strategy:
+    1. Extract library names from prompt
+    2. Check local cheatsheet store (hot tier — no MCP call needed)
+    3. Resolve library IDs via Context7 (cached) for misses
+    4. Query documentation (cached)
+    5. Transform to ContextItems
+
+    Args:
+        prompt: User's query/prompt
+        project: Optional project context (unused for Context7)
+
+    Returns:
+        List of ContextItems with documentation snippets
+    """
+    items = []
+
+    # Extract potential library names from prompt
+    library_names = _extract_library_names(prompt)
+    if not library_names:
+        return items
+
+    # For each library, try to get docs
+    for lib_name in library_names[:3]:  # Limit to 3 libraries
+        try:
+            # Try to get from cache first
+            cached = _cache.get(lib_name, prompt)
+            if cached is not None:
+                items.extend(cached)
+                continue
+
+            # Not cached - query Context7
+            lib_items = await _query_context7(lib_name, prompt)
+
+            # Cache results (even if empty)
+            _cache.set(lib_name, prompt, lib_items)
+
+            items.extend(lib_items)
+
+        except asyncio.TimeoutError:
+            print(f"Warning: Context7 query timeout for {lib_name}", file=sys.stderr)
+        except Exception as e:
+            print(f"Warning: Context7 query failed for {lib_name}: {e}", file=sys.stderr)
+
+    return items
+
+
+async def _query_context7(library_name: str, query: str, timeout: float = 5.0) -> List[ContextItem]:
+    """
+    Query Context7 for a specific library.
+
+    This function interfaces with the Context7 MCP tools if available.
+    Falls back gracefully if MCP integration is not present.
+
+    Args:
+        library_name: Name of the library (e.g., "react", "express")
+        query: The user's query
+        timeout: Query timeout in seconds
+
+    Returns:
+        List of ContextItems from Context7 docs
+    """
+    items = []
+
+    # Check if Context7 MCP tools are available
+    try:
+        # Import at runtime to avoid hard dependency
+        # This would be the MCP integration point
+        # For now, we'll use a subprocess approach to call MCP tools
+
+        # Step 1: Resolve library ID
+        library_id = await asyncio.wait_for(
+            _resolve_library_id(library_name, query),
+            timeout=timeout / 2
+        )
+
+        if not library_id:
+            return items
+
+        # Step 2: Query docs with library ID
+        docs = await asyncio.wait_for(
+            _query_docs(library_id, query),
+            timeout=timeout / 2
+        )
+
+        # Step 3: Transform to ContextItems
+        for idx, doc in enumerate(docs[:5]):  # Limit to 5 results
+            items.append(ContextItem(
+                id=f"context7:{library_id}:{idx}",
+                source="context7",
+                title=doc.get('title', f"{library_name} Documentation"),
+                summary=doc.get('summary', '')[:200],
+                excerpt=doc.get('content', '')[:500],
+                relevance=doc.get('score', 0.7),
+                age_days=0.0,  # External docs are current
+                metadata={
+                    'library_id': library_id,
+                    'library_name': library_name,
+                    'url': doc.get('url', ''),
+                    'source_type': 'external_docs',
+                }
+            ))
+
+    except asyncio.TimeoutError:
+        raise
+    except ImportError:
+        # MCP tools not available - graceful degradation
+        pass  # fail open: MCP tools optional
+    except Exception as e:
+        # Log but don't fail
+        print(f"Context7 query error: {e}", file=sys.stderr)
+
+    return items
+
+
+async def _resolve_library_id(library_name: str, query: str) -> Optional[str]:
+    """
+    Resolve library name to Context7 library ID.
+
+    Uses the Context7 MCP tool: resolve-library-id
+
+    Returns:
+        Library ID (e.g., "/vercel/next.js") or None
+    """
+    try:
+        # Call Claude Code to invoke MCP tool via subprocess
+        # In production, this would use the MCP client directly
+        # For now, simulate with a known mapping
+
+        # Common library mappings (fallback)
+        library_map = {
+            'react': '/facebook/react',
+            'nextjs': '/vercel/next.js',
+            'next': '/vercel/next.js',
+            'express': '/expressjs/express',
+            'fastapi': '/tiangolo/fastapi',
+            'django': '/django/django',
+            'flask': '/pallets/flask',
+            'vue': '/vuejs/core',
+            'angular': '/angular/angular',
+            'svelte': '/sveltejs/svelte',
+        }
+
+        normalized = library_name.lower().replace('.js', '').replace('-', '')
+        return library_map.get(normalized)
+
+    except Exception as e:
+        print(f"Library ID resolution failed for {library_name}: {e}", file=sys.stderr)
+        return None
+
+
+async def _query_docs(library_id: str, query: str) -> List[Dict[str, Any]]:
+    """
+    Query Context7 documentation for a library ID.
+
+    Uses the Context7 MCP tool: query-docs
+
+    Returns:
+        List of documentation snippets with metadata
+    """
+    try:
+        # In production, this would call the actual MCP tool
+        # For now, return empty list (graceful degradation)
+        # The MCP integration would happen at the hook level
+        return []
+
+    except Exception as e:
+        print(f"Doc query failed for {library_id}: {e}", file=sys.stderr)
+        return []
+
+
+def _extract_library_names(prompt: str) -> List[str]:
+    """
+    Extract potential library/framework names from prompt.
+
+    Uses heuristics to identify references to external libraries:
+    - Common library names
+    - Package manager patterns (npm install X, pip install X)
+    - Import statements
+
+    Args:
+        prompt: User's query text
+
+    Returns:
+        List of potential library names
+    """
+    import re
+
+    libraries = []
+    prompt_lower = prompt.lower()
+
+    # Pattern 1: Explicit library mentions with common keywords
+    library_patterns = [
+        r'\b(react|vue|angular|svelte|next(?:js)?|nuxt)\b',
+        r'\b(express|fastapi|django|flask|rails|spring)\b',
+        r'\b(mongodb|postgres|mysql|redis|elasticsearch)\b',
+        r'\b(typescript|python|java|rust|go)\b',
+        r'\b(jest|pytest|mocha|cypress|playwright)\b',
+        r'\b(webpack|vite|rollup|esbuild|parcel)\b',
+    ]
+
+    for pattern in library_patterns:
+        matches = re.findall(pattern, prompt_lower)
+        libraries.extend(matches)
+
+    # Pattern 2: Package manager install commands
+    install_patterns = [
+        r'npm install\s+(@?[\w-]+(?:/[\w-]+)?)',
+        r'pip install\s+([\w-]+)',
+        r'yarn add\s+(@?[\w-]+(?:/[\w-]+)?)',
+    ]
+
+    for pattern in install_patterns:
+        matches = re.findall(pattern, prompt_lower)
+        libraries.extend(matches)
+
+    # Pattern 3: Import statements
+    import_patterns = [
+        r'from\s+([\w-]+)\s+import',
+        r'import\s+([\w-]+)',
+        r'require\([\'"](@?[\w-]+(?:/[\w-]+)?)[\'"]',
+    ]
+
+    for pattern in import_patterns:
+        matches = re.findall(pattern, prompt)
+        libraries.extend(matches)
+
+    # Deduplicate and clean
+    unique_libs = []
+    seen = set()
+    for lib in libraries:
+        # Clean up library name
+        lib = lib.strip().lower()
+
+        # Skip built-ins and common false positives
+        skip_list = {'os', 'sys', 'json', 'time', 're', 'math', 'from', 'import'}
+        if lib in skip_list or len(lib) < 2:
+            continue
+
+        if lib not in seen:
+            seen.add(lib)
+            unique_libs.append(lib)
+
+    return unique_libs[:5]  # Limit to 5 libraries
+
+
+# Public API
+__all__ = ['query', 'Context7Cache']