bluera-knowledge 0.31.0 → 0.33.0

package/hooks/posttooluse-websearch-bk.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+PostToolUse hook for bluera-knowledge plugin.
+
+Fires after WebSearch tool calls. Checks if the search query relates to a
+library that is already indexed in BK, and if so reminds Claude to use BK
+search instead of relying solely on web results.
+
+Deduplicates per-project so the same store only triggers once per hour.
+"""
+
+import hashlib
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+
+# How long (seconds) before a seen store can trigger again
+DEDUP_TTL = 3600  # 1 hour
+
+# Minimum store name length to avoid false positives on short names
+MIN_STORE_NAME_LEN = 3
+
+
+def get_stores_path() -> Path | None:
+    """Get path to stores.json from project root."""
+    project_root = os.environ.get("PROJECT_ROOT") or os.environ.get("PWD")
+    if not project_root:
+        return None
+    return Path(project_root) / ".bluera" / "bluera-knowledge" / "data" / "stores.json"
+
+
+def load_stores() -> list[dict]:
+    """Load stores from stores.json. Returns empty list on error."""
+    stores_path = get_stores_path()
+    if stores_path is None or not stores_path.exists():
+        return []
+    try:
+        with open(stores_path, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            stores = data.get("stores", [])
+            return stores if isinstance(stores, list) else []
+        return data if isinstance(data, list) else []
+    except (json.JSONDecodeError, IOError, OSError):
+        return []
+
+
+def _dedup_path(project_root: str) -> str:
+    """Return the path to the per-project dedup file."""
+    h = hashlib.md5(project_root.encode()).hexdigest()[:8]
+    return f"/tmp/bk-websearch-{h}.json"
+
+
+def is_already_seen(store_name: str, project_root: str) -> bool:
+    """Check if this store was already flagged within the TTL."""
+    try:
+        path = _dedup_path(project_root)
+        with open(path) as f:
+            seen: dict[str, float] = json.load(f)
+        ts = seen.get(store_name, 0)
+        return (time.time() - ts) < DEDUP_TTL
+    except Exception:
+        return False
+
+
+def mark_seen(store_name: str, project_root: str) -> None:
+    """Record this store as seen, pruning expired entries."""
+    try:
+        path = _dedup_path(project_root)
+        now = time.time()
+        seen: dict[str, float] = {}
+        try:
+            with open(path) as f:
+                seen = json.load(f)
+        except Exception:
+            pass
+        seen = {k: v for k, v in seen.items() if (now - v) < DEDUP_TTL}
+        seen[store_name] = now
+        with open(path, "w") as f:
+            json.dump(seen, f)
+    except Exception:
+        pass
+
+
+def find_matching_stores(query: str, stores: list[dict]) -> list[str]:
+    """Find store names that appear in the search query."""
+    query_lower = query.lower()
+    matched = []
+    for store in stores:
+        name = store.get("name", "")
+        if len(name) < MIN_STORE_NAME_LEN:
+            continue
+        if name.lower() in query_lower:
+            matched.append(name)
+    return matched
+
+
+def main() -> int:
+    try:
+        stdin_data = sys.stdin.read()
+        if not stdin_data.strip():
+            return 0
+        hook_input = json.loads(stdin_data)
+
+        tool_name = hook_input.get("tool_name", "")
+        if tool_name != "WebSearch":
+            return 0
+
+        tool_input = hook_input.get("tool_input", {})
+        query = tool_input.get("query", "")
+        if not query:
+            return 0
+
+        stores = load_stores()
+        if not stores:
+            return 0
+
+        matched = find_matching_stores(query, stores)
+        if not matched:
+            return 0
+
+        project_root = os.environ.get("PROJECT_ROOT", os.environ.get("PWD", ""))
+
+        # Filter out already-seen stores
+        unseen = [s for s in matched if not is_already_seen(s, project_root)]
+        if not unseen:
+            return 0
+
+        for store_name in unseen:
+            mark_seen(store_name, project_root)
+
+        store_list = ", ".join(unseen)
+        message = (
+            f"You searched the web for a topic related to indexed libraries: {store_list}\n"
+            f"You have authoritative source code indexed in Bluera Knowledge.\n"
+            f"Use mcp__bluera-knowledge__search to get definitive answers from the actual source:\n"
+            f"  mcp__bluera-knowledge__search(query='{query}', intent='find-implementation')\n"
+            f"This is faster and more accurate than web results."
+        )
+
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": message,
+            }
+        }
+        print(json.dumps(output))
+        return 0
+
+    except Exception:
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/pretooluse-bk-suggest.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""
+PreToolUse hook for bluera-knowledge plugin.
+
+Fires before Claude reads/greps in dependency directories.
+- If library IS indexed in BK: BLOCKS the read and suggests BK search
+- If library NOT indexed: suggests BK but allows the read
+
+Escape hatch: Set BK_ALLOW_DIRECT_READ=1 env var to bypass all blocking.
+"""
+
+import json
+import logging
+import os
+import re
+import sys
+from pathlib import Path
+from typing import TypedDict
+
+
+class StoreDict(TypedDict, total=False):
+    """Store structure from stores.json."""
+
+    name: str
+    tags: list[str] | None
+    url: str | None
+
+
+class ToolInputDict(TypedDict, total=False):
+    """Tool input structure from hook."""
+
+    path: str  # For Grep
+    file_path: str  # For Read
+
+# Configure logging to stderr (stdout is for hook output)
+logging.basicConfig(
+    level=logging.DEBUG if os.environ.get("BK_DEBUG") else logging.WARNING,
+    format="%(name)s: %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger("bk-suggest")
+
+# Dependency path patterns with boundary markers to avoid false positives
+# like "my-node_modules-backup/"
+DEPENDENCY_PATTERNS = (
+    "/node_modules/",
+    "/vendor/",
+    "/site-packages/",
+    "/.venv/",
+    "/venv/",
+    "/bower_components/",
+    "/.npm/",
+    "/.cargo/registry/",
+    "/go/pkg/mod/",
+)
+
+# Blocking criteria - avoid false positives on ultra-common names
+MIN_NAME_LENGTH = 3
+COMMON_NAME_DENYLIST = frozenset([
+    "fs", "os", "core", "util", "utils", "lib", "src", "app", "api",
+    "test", "tests", "spec", "dist", "build", "bin", "pkg", "mod",
+])
+
+# Module-level cache for stores.json
+_stores_cache: list[StoreDict] = []
+_stores_mtime: float = 0.0
+_stores_path: Path | None = None
+
+
+def is_dependency_path(path: str) -> bool:
+    """Return True only if path is inside a dependency directory.
+
+    Uses boundary markers to avoid false positives like 'my-node_modules-backup/'.
+    """
+    # Normalize path separators and ensure leading slash for boundary matching
+    normalized = "/" + path.replace("\\", "/").lower()
+    return any(pattern in normalized for pattern in DEPENDENCY_PATTERNS)
+
+
+def extract_library_name(path: str) -> str | None:
+    """Extract library name from dependency path."""
+    # node_modules/package-name/... or node_modules/@scope/package/...
+    match = re.search(r"node_modules/(@[^/]+/[^/]+|[^/]+)", path)
+    if match:
+        return match.group(1)
+
+    # site-packages/package_name/...
+    match = re.search(r"site-packages/([^/]+)", path)
+    if match:
+        return match.group(1)
+
+    # vendor/package/...
+    match = re.search(r"vendor/([^/]+)", path)
+    if match:
+        return match.group(1)
+
+    # .cargo/registry/.../package-name-version/...
+    match = re.search(r"\.cargo/registry/[^/]+/([^/]+)-\d", path)
+    if match:
+        return match.group(1)
+
+    # go/pkg/mod/package@version/...
+    match = re.search(r"go/pkg/mod/([^@]+)@", path)
+    if match:
+        return match.group(1)
+
+    return None
+
+
+def normalize_name(name: str) -> str:
+    """Normalize library name for matching.
+
+    - Strips scope: @scope/pkg -> pkg
+    - Removes hyphens and underscores
+    - Lowercases
+    """
+    # Strip scope: @scope/pkg -> pkg
+    if "/" in name:
+        name = name.split("/")[-1]
+    # Remove hyphens, underscores, lowercase
+    return name.replace("-", "").replace("_", "").lower()
+
+
+def extract_repo_name(url: str | None) -> str | None:
+    """Extract repo name from URL like github.com/owner/repo."""
+    if not url:
+        return None
+    # github.com/owner/repo -> repo
+    # github.com/owner/repo.git -> repo
+    match = re.search(r"/([^/]+?)(?:\.git)?$", url)
+    return match.group(1) if match else None
+
+
+def get_stores_path() -> Path | None:
+    """Get path to stores.json from project root."""
+    project_root = os.environ.get("PROJECT_ROOT") or os.environ.get("PWD")
+    if not project_root:
+        return None
+    return Path(project_root) / ".bluera" / "bluera-knowledge" / "data" / "stores.json"
+
+
+def load_stores(stores_path: Path) -> list[StoreDict]:
+    """Load stores from stores.json. Returns empty list on error."""
+    if not stores_path.exists():
+        logger.debug("stores.json not found: %s", stores_path)
+        return []
+
+    try:
+        with open(stores_path, encoding="utf-8") as f:
+            data = json.load(f)
+            # Registry format: {"version": 1, "stores": [...]}
+            if isinstance(data, dict):
+                stores = data.get("stores", [])
+                return stores if isinstance(stores, list) else []
+            # Direct list format: [...]
+            return data if isinstance(data, list) else []
+    except (json.JSONDecodeError, IOError, OSError) as e:
+        logger.debug("Failed to read stores.json: %s", e)
+        return []
+
+
+def get_cached_stores() -> list[StoreDict]:
+    """Get stores with mtime-based cache invalidation."""
+    global _stores_cache, _stores_mtime, _stores_path
+
+    if _stores_path is None:
+        _stores_path = get_stores_path()
+    if _stores_path is None:
+        logger.debug("No project root found, skipping store check")
+        return []
+
+    try:
+        current_mtime = _stores_path.stat().st_mtime
+        if current_mtime != _stores_mtime:
+            logger.debug(
+                "Cache refresh: stores.json mtime changed (%.3f -> %.3f)",
+                _stores_mtime,
+                current_mtime,
+            )
+            _stores_cache = load_stores(_stores_path)
+            _stores_mtime = current_mtime
+    except (OSError, FileNotFoundError):
+        _stores_cache = []
+        _stores_mtime = 0.0
+
+    return _stores_cache
+
+
+def library_is_indexed(lib_name: str, stores: list[StoreDict]) -> str | None:
+    """Return matching store name if library is indexed, None otherwise.
+
+    Denylist is soft - if an EXACT store name match exists,
+    the denylist is overridden (user explicitly created a store for that name).
+    Tag/URL fuzzy matching is skipped for denylisted names.
+    """
+    if len(lib_name) < MIN_NAME_LENGTH:
+        return None  # Too short, skip
+
+    normalized = normalize_name(lib_name)
+    is_denylisted = lib_name.lower() in COMMON_NAME_DENYLIST
+
+    for store in stores:
+        store_name = store.get("name", "")
+
+        # Check store name - exact match overrides denylist
+        if normalize_name(store_name) == normalized:
+            return store_name
+
+        # If denylisted, skip tag/URL fuzzy matching (only exact store name counts)
+        if is_denylisted:
+            continue
+
+        # Check tags (only if not denylisted)
+        for tag in store.get("tags") or []:
+            if normalize_name(tag) == normalized:
+                return store_name
+
+        # Check repo URL (only if not denylisted)
+        repo_name = extract_repo_name(store.get("url"))
+        if repo_name and normalize_name(repo_name) == normalized:
+            return store_name
+
+    return None
+
+
+def get_path_from_input(tool_name: str, tool_input: ToolInputDict) -> str | None:
+    """Extract the path being accessed from tool input."""
+    if tool_name == "Grep":
+        return tool_input.get("path", "")
+    elif tool_name == "Read":
+        return tool_input.get("file_path", "")
+    return None
+
+
+def main() -> int:
+    try:
+        # Escape hatch: bypass all blocking if env var is set
+        if os.environ.get("BK_ALLOW_DIRECT_READ"):
+            logger.debug("Escape hatch: BK_ALLOW_DIRECT_READ env var set, bypassing")
+            return 0
+
+        stdin_data = sys.stdin.read()
+        if not stdin_data.strip():
+            return 0
+        hook_input = json.loads(stdin_data)
+
+        tool_name = hook_input.get("tool_name", "")
+        tool_input = hook_input.get("tool_input", {})
+
+        path = get_path_from_input(tool_name, tool_input)
+        if not path:
+            return 0
+
+        # Fast path: skip if not a dependency path (with boundary checking)
+        if not is_dependency_path(path):
+            return 0
+
+        lib_name = extract_library_name(path)
+        if not lib_name:
+            return 0
+
+        # Check if library is indexed in BK
+        stores = get_cached_stores()
+        matching_store = library_is_indexed(lib_name, stores)
+
+        if matching_store:
+            # BLOCK: Library is indexed, force BK usage
+            reason = f"'{lib_name}' is indexed in BK store '{matching_store}'. Use BK search tool instead."
+            output = {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "reasonForDecision": reason,
+                }
+            }
+            print(json.dumps(output))
+        else:
+            # SUGGEST: Library not indexed, allow but suggest
+            suggestion = f"TIP: '{lib_name}' isn't indexed in BK. Consider /bluera-knowledge:add-repo after this task."
+            output = {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "additionalContext": suggestion,
+                }
+            }
+            print(json.dumps(output))
+
+        return 0
+
+    except Exception as e:
+        logger.debug("Hook error, allowing: %s", e)
+        return 0  # Never block on unexpected errors
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/skill-activation.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""
+Skill activation hook for bluera-knowledge plugin.
+Matches user prompts against skill rules and injects activation reminders.
+
+Runs on UserPromptSubmit to detect users who would benefit from learning
+about BK skills, while excluding users who already know BK terminology.
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "enabled": True,
+    "threshold": 1,
+    "skills": {
+        "knowledge-search": True,
+        "when-to-query": True,
+        "search-optimization": True,
+        "advanced-workflows": True,
+        "store-lifecycle": True,
+    },
+}
+
+
+def get_project_root() -> Path | None:
+    """Get project root from environment variables (per-repo config)."""
+    # Check environment variables in priority order
+    for env_var in ["PROJECT_ROOT", "PWD"]:
+        value = os.environ.get(env_var, "")
+        if value:
+            return Path(value)
+    return None
+
+
+def get_config_path() -> Path | None:
+    """Get per-repo config path for skill activation."""
+    project_root = get_project_root()
+    if project_root is None:
+        return None
+    return project_root / ".bluera" / "bluera-knowledge" / "skill-activation.json"
+
+
+def load_config() -> dict[str, Any]:
+    """Load skill activation configuration from per-repo path."""
+    config_path = get_config_path()
+    if config_path is None or not config_path.exists():
+        return DEFAULT_CONFIG.copy()
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return DEFAULT_CONFIG.copy()
+
+
+def load_rules(plugin_root: Path) -> dict[str, Any]:
+    """Load skill rules from plugin hooks directory."""
+    rules_path = plugin_root / "hooks" / "skill-rules.json"
+    if not rules_path.exists():
+        return {"skills": [], "threshold": 1, "globalExclusions": []}
+    with open(rules_path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def matches_condition(prompt: str, condition: dict[str, Any]) -> bool:
+    """Check if prompt matches a single condition (keyword or regex)."""
+    prompt_lower = prompt.lower()
+    if "keyword" in condition:
+        return condition["keyword"].lower() in prompt_lower
+    if "regex" in condition:
+        return bool(re.search(condition["regex"], prompt, flags=re.IGNORECASE))
+    return False
+
+
+def check_exclusions(
+    prompt: str, exclusions: list[dict[str, Any]]
+) -> bool:
+    """Check if any exclusion pattern matches. Returns True if excluded."""
+    for exc in exclusions:
+        if matches_condition(prompt, exc):
+            return True
+    return False
+
+
+def score_skill(
+    prompt: str, skill: dict[str, Any]
+) -> tuple[int, list[str]]:
+    """Score a skill against the user prompt. Returns (score, reasons)."""
+    reasons: list[str] = []
+    score = 0
+
+    # Check skill-specific exclusions first
+    if check_exclusions(prompt, skill.get("exclusions", [])):
+        return 0, []
+
+    for trigger in skill.get("triggers", []):
+        if matches_condition(prompt, trigger):
+            weight = trigger.get("weight", 1)
+            score += weight
+            if "keyword" in trigger:
+                reasons.append(f'keyword "{trigger["keyword"]}"')
+            elif "regex" in trigger:
+                reasons.append(f'pattern match')
+
+    return score, reasons
+
+
+def generate_reminder(
+    matches: list[tuple[str, int, list[str], str]]
+) -> str:
+    """Generate assertive skill activation reminder using forced evaluation pattern."""
+    lines = [
+        "CRITICAL DIRECTIVE: Library/Dependency Question Detected",
+        "",
+        "BEFORE answering, you MUST:",
+        "",
+        "1. CHECK if a bluera-knowledge store exists for this library:",
+        "   → Use mcp__bluera-knowledge__execute(command='stores') to list indexed libraries",
+        "",
+        "2. IF INDEXED: Query the indexed source FIRST:",
+        "   → mcp__bluera-knowledge__search(query='your question', intent='find-implementation')",
+        "   → This is FASTER and more accurate than grepping node_modules/vendor",
+        "",
+        "3. IF NOT INDEXED: Suggest adding it:",
+        "   → Tell the user: '/bluera-knowledge:add-repo to index this library for future queries'",
+        "",
+        "MATCHED SKILLS (invoke for guidance):",
+    ]
+
+    for name, score, reasons, description in matches:
+        lines.append(f"  • Skill(skill='bluera-knowledge:{name}') - {description}")
+        lines.append(f"    Triggered by: {', '.join(reasons[:2])}")
+
+    lines.append("")
+    lines.append("WHY THIS MATTERS:")
+    lines.append("  - Grepping node_modules is SLOW (reads thousands of files)")
+    lines.append("  - Indexed search returns pre-chunked, semantic results")
+    lines.append("  - Token cost is 10-100x lower with indexed search")
+    lines.append("")
+    lines.append("FAILURE TO CONSULT INDEXED SOURCES = SUBOPTIMAL RESPONSE")
+
+    return "\n".join(lines)
+
+
+def main() -> int:
+    # Load configuration
+    config = load_config()
+
+    # Check if skill activation is enabled
+    if not config.get("enabled", True):
+        return 0
+
+    # Get plugin root from environment
+    plugin_root_env = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
+    if not plugin_root_env:
+        return 0
+    plugin_root = Path(plugin_root_env)
+
+    # Read hook input from stdin
+    try:
+        stdin_data = sys.stdin.read()
+        if not stdin_data.strip():
+            return 0
+        hook_input = json.loads(stdin_data)
+    except json.JSONDecodeError:
+        return 0
+
+    prompt = hook_input.get("prompt", "")
+    if not prompt.strip():
+        return 0
+
+    # Load rules
+    rules = load_rules(plugin_root)
+
+    # Check global exclusions first
+    if check_exclusions(prompt, rules.get("globalExclusions", [])):
+        return 0
+
+    threshold = config.get("threshold", rules.get("threshold", 1))
+    enabled_skills = config.get("skills", {})
+
+    # Score each skill
+    matches: list[tuple[str, int, list[str], str]] = []
+
+    for skill in rules.get("skills", []):
+        name = skill["name"]
+
+        # Skip disabled skills
+        if not enabled_skills.get(name, True):
+            continue
+
+        score, reasons = score_skill(prompt, skill)
+        if score >= threshold:
+            matches.append((name, score, reasons, skill.get("description", "")))
+
+    # No matches - silent exit
+    if not matches:
+        return 0
+
+    # Sort by score (highest first)
+    matches.sort(key=lambda t: t[1], reverse=True)
+
+    # Generate and output the reminder using proper JSON format
+    reminder = generate_reminder(matches)
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": reminder,
+        }
+    }
+    print(json.dumps(output))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())