bluera-knowledge 0.35.0 → 0.36.0

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "bluera-knowledge plugin hooks - auto-setup, readiness checks, job monitoring, and BK suggestions",
+  "description": "bluera-knowledge plugin hooks - auto-setup, readiness checks, job monitoring, activation nudges, and BK suggestions",
   "hooks": {
     "SessionStart": [
       {
@@ -72,6 +72,22 @@
             "command": "${CLAUDE_PLUGIN_ROOT:-.}/hooks/job-status-hook.sh",
             "timeout": 2,
             "async": true
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT:-.}/hooks/userpromptsubmit-bk-nudge.py",
+            "timeout": 2
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT:-.}/hooks/stop-bk-check.py",
+            "timeout": 2
           }
         ]
       }

package/hooks/stop-bk-check.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+Stop hook for bluera-knowledge plugin.
+
+Fires when Claude is about to stop responding. If the conversation
+involved dependency-related work but BK was never consulted, blocks
+once to suggest checking BK.
+
+Uses stop_hook_active for loop protection — only blocks the first time.
+"""
+
+import json
+import sys
+
+
+def main() -> None:
+    try:
+        stdin_data = sys.stdin.read()
+        if not stdin_data.strip():
+            return
+
+        data = json.loads(stdin_data)
+
+        # Loop protection: if stop hook already fired, allow stop
+        stop_hook_active = data.get("stop_hook_active", False)
+        if stop_hook_active:
+            return
+
+        # Check if BK tools were used in this conversation
+        # The tool_uses field contains tools used so far in the session
+        tool_uses = data.get("tool_uses", [])
+
+        bk_was_used = False
+        has_dependency_context = False
+
+        for tool_use in tool_uses:
+            tool_name = ""
+            if isinstance(tool_use, dict):
+                tool_name = tool_use.get("tool_name", tool_use.get("name", ""))
+            elif isinstance(tool_use, str):
+                tool_name = tool_use
+
+            # Check if BK search was used
+            if "bluera-knowledge" in tool_name and (
+                "search" in tool_name or "get_full_context" in tool_name
+            ):
+                bk_was_used = True
+                break
+
+            # Check if dependency dirs were accessed (Read/Grep in node_modules etc.)
+            tool_input = (
+                tool_use.get("tool_input", {}) if isinstance(tool_use, dict) else {}
+            )
+            path = tool_input.get("path", tool_input.get("file_path", ""))
+            if isinstance(path, str):
+                dep_markers = (
+                    "/node_modules/",
+                    "/vendor/",
+                    "/site-packages/",
+                    "/.venv/",
+                )
+                if any(marker in path for marker in dep_markers):
+                    has_dependency_context = True
+
+        # If BK was used or no dependency context detected, allow stop
+        if bk_was_used or not has_dependency_context:
+            return
+
+        # Block stop once — suggest checking BK
+        output = {
+            "decision": "block",
+            "reason": (
+                "You accessed dependency directories but haven't consulted Bluera Knowledge. "
+                "Consider using mcp__bluera-knowledge__search to verify your answer "
+                "against authoritative source code before completing."
+            ),
+        }
+        print(json.dumps(output))
+
+    except Exception:
+        # Hooks must never crash — silent failure allows stop
+        pass
+
+
+if __name__ == "__main__":
+    main()

package/hooks/userpromptsubmit-bk-nudge.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""
+UserPromptSubmit hook for bluera-knowledge plugin.
+
+Detects dependency-related prompts and injects a gentle BK reminder
+into context, reinforcing the directive skill description.
+
+Fires when:
+- Prompt mentions dependency errors (Cannot find module, ModuleNotFoundError, etc.)
+- Prompt involves planning/implementing with external packages
+- Prompt mentions debugging + library/package keywords
+- Prompt contains import/require statements with package names
+
+Does NOT fire when:
+- Prompt already mentions bluera-knowledge, /search, or mcp__bluera-knowledge
+- No dependency-related content detected
+"""
+
+import json
+import re
+import sys
+
+
+# Patterns that indicate dependency-related work
+DEPENDENCY_ERROR_PATTERNS = [
+    r"cannot find module",
+    r"module not found",
+    r"modulenotfounderror",
+    r"importerror",
+    r"no module named",
+    r"package .+ not found",
+    r"could not resolve",
+    r"cannot resolve",
+    r"peer dep",
+    r"unresolved import",
+]
+
+LIBRARY_KEYWORDS = [
+    r"\b(?:dependency|dependencies|package|library|framework|sdk|api)\b",
+    r"\b(?:npm|pip|cargo|gem|maven|gradle|composer|nuget)\b",
+    r"\b(?:node_modules|vendor|site-packages|\.venv)\b",
+    r"\b(?:import|require|from .+ import)\b.*\b(?:express|react|vue|angular|fastapi|django|flask|hono|zod|pydantic|axios|lodash|prisma|drizzle|next|svelte|tailwind)\b",
+]
+
+PLANNING_PATTERNS = [
+    r"\b(?:implement|integrate|set up|configure|use|add)\b.{1,40}\b(?:with|using)\b",
+    r"\bhow (?:does|do|to)\b.{1,30}\b(?:work|handle|process)\b",
+    r"\bwhat (?:is|are|does)\b.{1,30}\b(?:api|method|function|class|option|parameter)\b",
+]
+
+DEBUG_PATTERNS = [
+    r"\b(?:error|bug|issue|crash|fail|broken|stuck|debug)\b.{1,60}\b(?:package|library|dependency|module|import)\b",
+    r"\b(?:package|library|dependency|module|import)\b.{1,60}\b(?:error|bug|issue|crash|fail|broken|stuck|debug)\b",
+]
+
+# Patterns indicating the user is already using BK
+ALREADY_USING_BK = [
+    r"bluera.knowledge",
+    r"/search",
+    r"/bluera-knowledge",
+    r"mcp__bluera.knowledge",
+    r"mcp__.*bluera.*knowledge",
+]
+
+
+def prompt_involves_dependencies(prompt: str) -> bool:
+    """Check if the prompt involves dependency/library work."""
+    lower = prompt.lower()
+
+    for pattern in DEPENDENCY_ERROR_PATTERNS:
+        if re.search(pattern, lower):
+            return True
+
+    for pattern in LIBRARY_KEYWORDS:
+        if re.search(pattern, lower, re.IGNORECASE):
+            return True
+
+    for pattern in PLANNING_PATTERNS:
+        if re.search(pattern, lower, re.IGNORECASE):
+            return True
+
+    for pattern in DEBUG_PATTERNS:
+        if re.search(pattern, lower, re.IGNORECASE):
+            return True
+
+    return False
+
+
+def already_using_bk(prompt: str) -> bool:
+    """Check if the prompt already references BK."""
+    lower = prompt.lower()
+    for pattern in ALREADY_USING_BK:
+        if re.search(pattern, lower):
+            return True
+    return False
+
+
+def main() -> None:
+    try:
+        stdin_data = sys.stdin.read()
+        if not stdin_data.strip():
+            return
+
+        data = json.loads(stdin_data)
+        prompt = data.get("prompt", "")
+
+        if not prompt:
+            return
+
+        # Don't fire if user is already using BK
+        if already_using_bk(prompt):
+            return
+
+        # Don't fire if prompt doesn't involve dependencies
+        if not prompt_involves_dependencies(prompt):
+            return
+
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": (
+                    "You have indexed library sources available via Bluera Knowledge. "
+                    "Use mcp__bluera-knowledge__search to look up library APIs, "
+                    "implementation details, and usage patterns before relying on training data."
+                ),
+            }
+        }
+        print(json.dumps(output))
+
+    except Exception:
+        # Hooks must never crash — silent failure is safer than blocking
+        pass
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {

package/scripts/auto-setup.sh

@@ -30,11 +30,18 @@ log_debug() {
 
 log_debug "Auto-setup starting, PLUGIN_ROOT=$PLUGIN_ROOT"
 
-# Fast exit if already set up
+# Fast exit if already set up AND version hasn't changed
 WRAPPER_PATH="$HOME/.local/bin/bluera-knowledge-mcp"
+VERSION_FILE="$PLUGIN_ROOT/.installed-version"
+CURRENT_VERSION=$(cat "$PLUGIN_ROOT/package.json" 2>/dev/null | grep '"version"' | head -1 | sed 's/.*"\([0-9][0-9.]*\)".*/\1/')
+INSTALLED_VERSION=$(cat "$VERSION_FILE" 2>/dev/null || echo "none")
+
 if [ -d "$PLUGIN_ROOT/node_modules" ] && [ -f "$WRAPPER_PATH" ]; then
-    log_debug "Already set up (node_modules and wrapper exist), exiting"
-    exit 0
+    if [ "$CURRENT_VERSION" = "$INSTALLED_VERSION" ]; then
+        log_debug "Already set up (v$INSTALLED_VERSION), exiting"
+        exit 0
+    fi
+    log_debug "Version changed ($INSTALLED_VERSION -> $CURRENT_VERSION), re-running setup"
 fi
 
 log_debug "Setup needed - node_modules: $([ -d "$PLUGIN_ROOT/node_modules" ] && echo 'exists' || echo 'missing'), wrapper: $([ -f "$WRAPPER_PATH" ] && echo 'exists' || echo 'missing')"
@@ -60,6 +67,7 @@ echo -e "${YELLOW}[bluera-knowledge] Running first-time setup (this may take a m
 export NONINTERACTIVE=1
 if "$PLUGIN_ROOT/scripts/setup.sh"; then
     log_debug "Setup completed successfully"
+    echo "$CURRENT_VERSION" > "$VERSION_FILE" 2>/dev/null || true
     echo -e "${GREEN}[bluera-knowledge] Setup complete ✓${NC}"
     echo -e "${GREEN}[bluera-knowledge] Restart Claude Code to enable MCP server.${NC}"
 else

package/skills/knowledge-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-search
-description: Use when the user asks about libraries, frameworks, dependencies, API references, implementation details, or needs code examples from third-party packages. Activates for library API questions, dependency errors, framework configuration, or code generation involving external packages.
+description: Library and dependency expert. ALWAYS invoke this skill when working with third-party libraries, frameworks, or dependencies — including debugging dependency errors, planning code that uses external packages, checking API signatures, or understanding library internals. Do not grep node_modules, vendor directories, or rely on training data for library questions directly — use this skill first.
 ---
 
 # Using Bluera Knowledge (BK)

package/skills/suggest/SKILL.md

@@ -28,16 +28,23 @@ Analyze project dependencies and suggest important libraries to add to knowledge
    - Count imports/requires for each dependency
    - Rank dependencies by frequency of use
 
-4. **Get existing stores** using mcp__bluera-knowledge__execute with command "stores":
+4. **Select the IMPORTANT dependencies** — not all of them. Apply these criteria:
+   - Prioritize core frameworks and libraries the project builds ON (e.g., React, Express, FastAPI)
+   - Include libraries with complex APIs where understanding internals helps (e.g., Prisma, Drizzle, Zod)
+   - Include deps likely to cause debugging issues or have non-obvious behavior
+   - **Skip**: test runners (jest, vitest, pytest), linters (eslint, ruff), formatters (prettier, black), build tools (webpack, vite, esbuild), @types packages, trivial utilities
+   - Aim for 5-10 most impactful dependencies, not every dependency
+
+5. **Get existing stores** using mcp__bluera-knowledge__execute with command "stores":
    - Filter out dependencies already in stores
    - Focus on new suggestions
 
-5. **Find repository URLs** using WebSearch:
-   - For top 5 most-used dependencies
+6. **Find repository URLs** using WebSearch:
+   - For the selected important dependencies
    - Search for official GitHub/GitLab repositories
    - Prefer official repos over forks
 
-6. **Present selectable list** using AskUserQuestion:
+7. **Present selectable list** using AskUserQuestion:
 
 First, show a summary of what was found:
 ```
@@ -79,7 +86,7 @@ Then use AskUserQuestion with multiSelect to let the user choose which to add:
 
 **Note:** Maximum 4 options per question (AskUserQuestion limit). If more than 4 dependencies, show top 4 and mention others in summary.
 
-7. **Execute selected add-repo commands**:
+8. **Execute selected add-repo commands**:
 
 For each selected dependency, invoke the Skill tool:
 ```
@@ -91,7 +98,7 @@ Example for react selection:
 Skill(skill="bluera-knowledge:add-repo", args="https://github.com/facebook/react --name=react")
 ```
 
-8. **Show completion summary**:
+9. **Show completion summary**:
 ```
 ## Added to Knowledge Stores