bluera-knowledge 0.34.1 → 0.35.0

package/hooks/pretooluse-bk-suggest.py

@@ -1,296 +0,0 @@
-#!/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

@@ -1,221 +0,0 @@
-#!/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())

package/hooks/skill-rules.json

@@ -1,131 +0,0 @@
-{
-  "description": "bluera-knowledge skill activation rules - technology-agnostic patterns for development scenarios",
-  "version": 2,
-  "globalExclusions": [
-    { "keyword": "bluera-knowledge" },
-    { "keyword": "bluera knowledge" },
-    { "keyword": "/bluera-knowledge:" },
-    { "regex": "mcp__.*bluera" }
-  ],
-  "threshold": 2,
-  "skills": [
-    {
-      "name": "knowledge-search",
-      "description": "How to query Bluera Knowledge for library/dependency questions",
-      "triggers": [
-        { "regex": "the\\s+\\w+(-\\w+)*\\s+(package|library|module|framework|dependency)", "weight": 3 },
-        { "regex": "\\w+(-\\w+)*\\s+(package|library|module)\\s+(is|does|keeps|isn't|won't|doesn't)", "weight": 3 },
-        { "regex": "\\w+(-\\w+)*\\s+(documentation|docs)\\b", "weight": 2 },
-        { "regex": "error\\s+(from|in|with)\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library|module)", "weight": 3 },
-        { "regex": "(package|library|dependency|module)\\s+(is\\s+)?(throwing|throws|error|failing)", "weight": 3 },
-        { "regex": "how\\s+does\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library|module|framework)\\s+(handle|work|process)", "weight": 3 },
-        { "regex": "what\\s+does\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library)\\s+(do|return|accept)", "weight": 3 },
-        { "regex": "why\\s+does\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library|module)", "weight": 3 },
-        { "regex": "(configure|config|settings)\\s+(for\\s+)?(the\\s+)?\\w+(-\\w+)*\\s+(package|library)", "weight": 3 },
-        { "regex": "(upgraded?|updated?)\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library|dependency)", "weight": 2 },
-        { "regex": "integrate\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library)", "weight": 2 },
-        { "regex": "dependency\\s+(is|keeps|isn't|won't|error|issue|problem)", "weight": 2 },
-        { "regex": "third[- ]party\\s+(library|package|code)", "weight": 2 },
-        { "regex": "look\\s+(at|in|into)\\s+(the\\s+)?\\w+(-\\w+)*\\s+(source|code|internals)", "weight": 3 },
-        { "regex": "\\w+(-\\w+)*\\s+source\\s+code", "weight": 2 },
-        { "regex": "(find|show|get)\\s+(me\\s+)?(the\\s+)?\\w+(-\\w+)*\\s+(implementation|source|code)", "weight": 3 },
-        { "regex": "TypeError|ImportError|ModuleNotFoundError|AttributeError", "weight": 2 },
-        { "regex": "\\w+(-\\w+)*\\s+is\\s+(deprecated|removed|changed)", "weight": 2 },
-        { "regex": "breaking\\s+change.*(\\w+(-\\w+)*\\s+)?(package|library|dependency)", "weight": 3 },
-        { "regex": "migrate\\s+(from|to)\\s+\\w+(-\\w+)*", "weight": 2 }
-      ],
-      "exclusions": [
-        { "keyword": "my code" },
-        { "keyword": "our code" },
-        { "keyword": "this function" },
-        { "keyword": "this file" },
-        { "keyword": "this component" },
-        { "keyword": "this class" },
-        { "keyword": "this project" },
-        { "keyword": "I wrote" },
-        { "keyword": "we wrote" },
-        { "keyword": "my implementation" },
-        { "keyword": "store" },
-        { "keyword": "index" },
-        { "keyword": "in my" },
-        { "keyword": "in our" }
-      ]
-    },
-    {
-      "name": "when-to-query",
-      "description": "Decision guide for Bluera Knowledge vs Grep/Read",
-      "triggers": [
-        { "keyword": "should i grep", "weight": 2 },
-        { "keyword": "where should i look", "weight": 2 },
-        { "keyword": "grep or search", "weight": 2 },
-        { "keyword": "search or grep", "weight": 2 },
-        { "regex": "where\\s+(should|do)\\s+i\\s+(find|look)\\s+.*(library|package|dependency)", "weight": 3 },
-        { "regex": "is\\s+there\\s+a\\s+better\\s+way\\s+to\\s+(search|find)", "weight": 2 },
-        { "regex": "should\\s+i\\s+(use\\s+)?grep\\s+(for|to)", "weight": 2 },
-        { "regex": "how\\s+(do|should)\\s+i\\s+find.*(in|from)\\s+(a\\s+)?(library|package|dependency)", "weight": 3 }
-      ],
-      "exclusions": [
-        { "keyword": "store" },
-        { "keyword": "index" }
-      ]
-    },
-    {
-      "name": "search-optimization",
-      "description": "Optimizing search parameters and token usage",
-      "triggers": [
-        { "keyword": "too many results", "weight": 2 },
-        { "keyword": "too few results", "weight": 2 },
-        { "keyword": "limit results", "weight": 2 },
-        { "keyword": "reduce tokens", "weight": 2 },
-        { "keyword": "token usage", "weight": 2 },
-        { "keyword": "optimize search", "weight": 2 },
-        { "keyword": "detail level", "weight": 2 },
-        { "regex": "\\b(minimal|contextual|full)\\s+detail", "weight": 2 },
-        { "regex": "\\b(vector|fts|hybrid)\\s+(search|mode)", "weight": 2 },
-        { "regex": "narrow\\s+(down\\s+)?(the\\s+)?results", "weight": 2 },
-        { "regex": "search\\s+(is\\s+)?(returning|giving)\\s+(too\\s+)?(many|few)", "weight": 2 }
-      ],
-      "exclusions": [
-        { "regex": "--?(limit|detail|mode|threshold)\\s*=" }
-      ]
-    },
-    {
-      "name": "advanced-workflows",
-      "description": "Multi-tool orchestration patterns",
-      "triggers": [
-        { "keyword": "multi-step", "weight": 2 },
-        { "keyword": "orchestration", "weight": 2 },
-        { "keyword": "job monitoring", "weight": 2 },
-        { "keyword": "background job", "weight": 2 },
-        { "keyword": "combine tools", "weight": 2 },
-        { "keyword": "chain operations", "weight": 2 },
-        { "regex": "chain.*searches", "weight": 2 },
-        { "regex": "multiple.*searches", "weight": 2 },
-        { "regex": "search.*then\\s+(summarize|extract|filter)", "weight": 2 },
-        { "regex": "for\\s+each\\s+(search\\s+)?(result|match)", "weight": 2 }
-      ],
-      "exclusions": []
-    },
-    {
-      "name": "store-lifecycle",
-      "description": "Managing knowledge stores",
-      "triggers": [
-        { "keyword": "add store", "weight": 2 },
-        { "keyword": "create store", "weight": 2 },
-        { "keyword": "delete store", "weight": 2 },
-        { "keyword": "remove store", "weight": 2 },
-        { "keyword": "index store", "weight": 2 },
-        { "keyword": "re-index", "weight": 2 },
-        { "keyword": "reindex", "weight": 2 },
-        { "keyword": "knowledge store", "weight": 2 },
-        { "regex": "add\\s+(a\\s+)?(repo|repository|folder|directory)\\s+(to|for)\\s+(knowledge|indexing|search)", "weight": 3 },
-        { "regex": "index\\s+(a|the|my)\\s+(repo|repository|folder|directory|library|package)", "weight": 2 },
-        { "regex": "set\\s+up.*(knowledge|search)\\s*(store|index)", "weight": 2 },
-        { "regex": "(backup|snapshot|archive).*(knowledge|search)\\s*(store|index)", "weight": 2 }
-      ],
-      "exclusions": [
-        { "regex": "/bluera-knowledge:(add-repo|add-folder|remove-store|index)" }
-      ]
-    }
-  ]
-}