bluera-knowledge 0.31.0 → 0.33.0

package/dist/mcp/server.d.ts

@@ -882,7 +882,7 @@ type SearchMode = 'vector' | 'fts' | 'hybrid';
  * Search intent hints for context-aware ranking.
  * These align with the MCP API contract.
  */
-type SearchIntent = 'find-pattern' | 'find-implementation' | 'find-usage' | 'find-definition' | 'find-documentation';
+type SearchIntent = 'find-pattern' | 'find-implementation' | 'find-usage' | 'find-definition' | 'find-documentation' | 'find-files';
 interface CodeUnit {
     type: 'function' | 'class' | 'interface' | 'type' | 'const' | 'documentation' | 'example';
     name: string;
@@ -899,6 +899,7 @@ interface ResultSummary {
     readonly purpose: string;
     readonly location: string;
     readonly relevanceReason: string;
+    readonly relatedFiles?: readonly string[];
 }
 interface ResultContext {
     readonly interfaces: readonly string[];
@@ -1079,9 +1080,10 @@ declare class SearchService {
      */
     private getUsageFromGraph;
     /**
-     * Get related code from graph.
-     * Returns callers and callees for the symbol.
+     * Get related file paths from code graph edges for follow-up reads.
+     * Returns unique file paths (max 5) from callers/callees, excluding the result's own file.
      */
+    private getRelatedFilePaths;
     private getRelatedCodeFromGraph;
     /**
      * Parse a node ID into file path and symbol name.

package/dist/mcp/server.js

@@ -1,8 +1,8 @@
 import {
   createMCPServer,
   runMCPServer
-} from "../chunk-AEXFPA57.js";
-import "../chunk-B335UOU7.js";
+} from "../chunk-YDTTD53Y.js";
+import "../chunk-3TB7TDVF.js";
 import "../chunk-CLIMKLTW.js";
 import "../chunk-N3XYMAU3.js";
 import "../chunk-DGUM43GV.js";

package/dist/workers/background-worker-cli.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import {
   IntelligentCrawler
-} from "../chunk-KCI4U6FH.js";
+} from "../chunk-KDZDLJUY.js";
 import {
   JobService,
   createLogger,
   createServices,
   destroyServices,
   shutdownLogger
-} from "../chunk-B335UOU7.js";
+} from "../chunk-3TB7TDVF.js";
 import {
   createDocumentId,
   createStoreId

package/hooks/check-ready.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# Bluera Knowledge Plugin - Readiness Check
+# Runs on: every SessionStart - must be FAST (<5s)
+#
+# This script only CHECKS if setup is complete.
+# Auto-setup runs async via auto-setup.sh on SessionStart.
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$0")")}"
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+# Debug logging - writes JSON to same log file as bootstrap.ts
+# Uses PROJECT_ROOT if available (set by Claude Code), else current dir
+LOG_DIR="${PROJECT_ROOT:-.}/.bluera/bluera-knowledge/logs"
+LOG_FILE="$LOG_DIR/app.log"
+
+log_debug() {
+    local msg="$1"
+    mkdir -p "$LOG_DIR" 2>/dev/null || true
+    # macOS date doesn't support %3N, fallback to seconds-only
+    local timestamp
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+    echo "{\"time\":\"$timestamp\",\"level\":\"debug\",\"module\":\"check-ready.sh\",\"msg\":\"$msg\"}" >> "$LOG_FILE" 2>/dev/null || true
+}
+
+log_debug "Check-ready starting, PLUGIN_ROOT=$PLUGIN_ROOT, PROJECT_ROOT=${PROJECT_ROOT:-unset}"
+
+missing_setup=false
+
+# Fast check: node_modules exists?
+log_debug "Checking node_modules at $PLUGIN_ROOT/node_modules"
+if [ ! -d "$PLUGIN_ROOT/node_modules" ]; then
+    log_debug "node_modules missing"
+    echo -e "${YELLOW}[bluera-knowledge] ⚠️  Dependencies not installed. Setup running in background...${NC}"
+    missing_setup=true
+else
+    log_debug "node_modules exists"
+fi
+
+# Fast check: MCP wrapper script installed?
+# The wrapper is installed to ~/.local/bin/bluera-knowledge-mcp by setup.sh
+# Without it, MCP server can't start (workaround for CLAUDE_PLUGIN_ROOT bug #9427)
+WRAPPER_PATH="$HOME/.local/bin/bluera-knowledge-mcp"
+log_debug "Checking MCP wrapper at $WRAPPER_PATH"
+if [ ! -f "$WRAPPER_PATH" ]; then
+    log_debug "MCP wrapper missing"
+    echo -e "${YELLOW}[bluera-knowledge] ⚠️  MCP wrapper not installed. Setup running in background...${NC}"
+    missing_setup=true
+else
+    log_debug "MCP wrapper exists"
+fi
+
+# Fast check: build tools available?
+# Native modules require make/gcc - this is a BLOCKING prerequisite
+# Note: SessionStart stderr doesn't display (Bug #12653), so write to /dev/tty
+log_debug "Checking build tools (make)"
+if ! command -v make &>/dev/null; then
+    log_debug "Build tools (make) not found - blocking error"
+    ERROR_MSG="[bluera-knowledge] ERROR: Build tools (make) not found - required for native modules.
+
+Install build tools, then restart Claude Code:
+  Debian/Ubuntu: sudo apt install build-essential
+  Fedora/RHEL:   sudo dnf groupinstall 'Development Tools'
+  macOS:         xcode-select --install"
+
+    # Write to /dev/tty for immediate visibility (workaround for Bug #12653)
+    if [ -w /dev/tty ]; then
+        printf "\033[1;31m%s\033[0m\n" "$ERROR_MSG" > /dev/tty 2>/dev/null || true
+    fi
+    # Also write to stderr in case bug is fixed
+    echo "$ERROR_MSG" >&2
+    exit 2
+fi
+log_debug "Build tools (make) available"
+
+# Fast check: Playwright Chromium installed?
+PLAYWRIGHT_BROWSERS_PATH="${PLAYWRIGHT_BROWSERS_PATH:-$HOME/.cache/ms-playwright}"
+log_debug "Checking playwright at $PLAYWRIGHT_BROWSERS_PATH/chromium-*"
+if ! ls "$PLAYWRIGHT_BROWSERS_PATH"/chromium-* 1>/dev/null 2>&1; then
+    log_debug "Playwright chromium missing"
+    if [ "$missing_setup" = false ]; then
+        echo -e "${YELLOW}[bluera-knowledge] ⚠️  Playwright browser not installed. Setup running in background...${NC}"
+    fi
+    missing_setup=true
+else
+    log_debug "Playwright chromium exists"
+fi
+
+# If setup is complete, show ready message
+if [ "$missing_setup" = false ]; then
+    log_debug "All checks passed, checking python3"
+    # Optional: quick Python check (informational only)
+    if command -v python3 &>/dev/null; then
+        python_version=$(python3 -c 'import sys; print(".".join(map(str, sys.version_info[:2])))' 2>/dev/null || echo "unknown")
+        log_debug "Python $python_version found"
+        echo -e "${GREEN}[bluera-knowledge] Ready ✓ (Python ${python_version} available)${NC}"
+    else
+        log_debug "Python3 not found"
+        echo -e "${GREEN}[bluera-knowledge] Ready ✓${NC}"
+    fi
+fi
+
+log_debug "Check-ready complete, missing_setup=$missing_setup"
+
+# Always exit 0 to not block the session
+exit 0

package/hooks/hooks.json

@@ -0,0 +1,97 @@
+{
+  "description": "bluera-knowledge plugin hooks - auto-setup, readiness checks, job monitoring, and BK suggestions",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT:-.}/scripts/auto-setup.sh",
+            "timeout": 300,
+            "async": true
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT:-.}/hooks/check-ready.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Grep|Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT:-.}/hooks/pretooluse-bk-suggest.py",
+            "timeout": 2
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT:-.}/hooks/posttooluse-bk-reminder.py",
+            "timeout": 3
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT:-.}/hooks/posttooluse-bk-reminder.py",
+            "timeout": 3
+          }
+        ]
+      },
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT:-.}/hooks/posttooluse-websearch-bk.py",
+            "timeout": 2
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__.*bluera-knowledge__search",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'TIP: Use mcp__bluera-knowledge__get_full_context with the result ID for complete code context.'",
+            "timeout": 1
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT:-.}/hooks/job-status-hook.sh",
+            "timeout": 2,
+            "async": true
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT:-.}/hooks/skill-activation.py",
+            "timeout": 2
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/job-status-hook.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Show active jobs in context when user submits a prompt
+#
+# This hook runs on UserPromptSubmit events and injects
+# information about active background jobs into the context.
+
+JOBS_DIR="$HOME/.local/share/bluera-knowledge/jobs"
+
+# Exit silently if jobs directory doesn't exist
+if [ ! -d "$JOBS_DIR" ]; then
+  exit 0
+fi
+
+# Find active jobs (modified in last 60 minutes)
+active_jobs=$(find "$JOBS_DIR" -name "*.json" -type f -not -name "*.pid" -mmin -60 2>/dev/null | while read -r file; do
+  # Skip if file doesn't exist or isn't readable
+  if [ ! -r "$file" ]; then
+    continue
+  fi
+
+  # Extract job details using jq (if available) or grep fallback
+  if command -v jq >/dev/null 2>&1; then
+    status=$(jq -r '.status' "$file" 2>/dev/null || echo "unknown")
+    if [ "$status" = "running" ] || [ "$status" = "pending" ]; then
+      job_id=$(basename "$file" .json)
+      type=$(jq -r '.type' "$file" 2>/dev/null || echo "unknown")
+      progress=$(jq -r '.progress' "$file" 2>/dev/null || echo "0")
+      message=$(jq -r '.message' "$file" 2>/dev/null || echo "No message")
+      echo "- $type job ($job_id): ${progress}% - $message"
+    fi
+  else
+    # Fallback using grep if jq not available
+    status=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$file" | cut -d'"' -f4)
+    if [ "$status" = "running" ] || [ "$status" = "pending" ]; then
+      job_id=$(basename "$file" .json)
+      type=$(grep -o '"type"[[:space:]]*:[[:space:]]*"[^"]*"' "$file" | cut -d'"' -f4)
+      progress=$(grep -o '"progress"[[:space:]]*:[[:space:]]*[0-9.]*' "$file" | awk '{print $NF}')
+      message=$(grep -o '"message"[[:space:]]*:[[:space:]]*"[^"]*"' "$file" | cut -d'"' -f4)
+      echo "- $type job ($job_id): ${progress}% - $message"
+    fi
+  fi
+done)
+
+# Output active jobs if any found
+if [ -n "$active_jobs" ]; then
+  echo ""
+  echo "Active background jobs:"
+  echo "$active_jobs"
+  echo ""
+  echo "Check status with: /bluera-knowledge:check-status"
+fi

package/hooks/posttooluse-bk-reminder.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+PostToolUse hook for bluera-knowledge plugin.
+
+Fires after Claude reads/greps in dependency directories,
+reminding to consider using BK for similar future queries.
+
+Note: If pretooluse blocked the read (library was indexed), this hook won't fire.
+This hook only fires for non-indexed libraries that were allowed through.
+"""
+
+import json
+import re
+import sys
+from typing import TypedDict
+
+
+class ToolInputDict(TypedDict, total=False):
+    """Tool input structure from hook."""
+
+    path: str  # For Grep
+    file_path: str  # For Read
+
+
+# Dependency path patterns with boundary markers to avoid false positives
+DEPENDENCY_PATTERNS = (
+    "/node_modules/",
+    "/vendor/",
+    "/site-packages/",
+    "/.venv/",
+    "/venv/",
+    "/bower_components/",
+    "/.npm/",
+    "/.cargo/registry/",
+    "/go/pkg/mod/",
+)
+
+
+def is_dependency_path(path: str) -> bool:
+    """Return True only if path is inside a dependency directory."""
+    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 check_tool(tool_name: str, tool_input: ToolInputDict) -> tuple[str | None, str | None]:
+    """Check if tool targeted library code. Returns (action, library_name)."""
+    if tool_name == "Grep":
+        path = tool_input.get("path", "")
+    elif tool_name == "Read":
+        path = tool_input.get("file_path", "")
+    else:
+        return None, None
+
+    if not path or not is_dependency_path(path):
+        return None, None
+
+    lib_name = extract_library_name(path)
+    action = f"read `{path}`" if tool_name == "Read" else f"grepped in `{path}`"
+    return action, lib_name
+
+
+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", "")
+        tool_input = hook_input.get("tool_input", {})
+
+        action, lib_name = check_tool(tool_name, tool_input)
+        if not action:
+            return 0
+
+        # Build concise reminder
+        lib_hint = f" ({lib_name})" if lib_name else ""
+        add_hint = f"Consider: /bluera-knowledge:add-repo {lib_name}" if lib_name else ""
+
+        reminder = f"You just {action}{lib_hint}. For future queries, use BK search. {add_hint}"
+
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": reminder.strip(),
+            }
+        }
+        print(json.dumps(output))
+        return 0
+
+    except Exception:
+        return 0  # Never fail on errors
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/posttooluse-web-research.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""
+PostToolUse hook for bluera-knowledge plugin.
+
+Fires after Claude fetches from source code hosting or package registry URLs.
+Emits a mandatory reminder to index the library with BK if it will be used
+in the project. Deduplicates per-project so the same repo only triggers once
+per hour.
+"""
+
+import hashlib
+import json
+import os
+import re
+import sys
+import time
+from typing import TypedDict
+
+
+class RepoInfo(TypedDict):
+    """Extracted repository/package information from a URL."""
+
+    canonical_url: str  # e.g., "https://github.com/ml-explore/mlx-lm"
+    name: str  # e.g., "mlx-lm"
+    command: str  # e.g., "/bluera-knowledge:add-repo https://github.com/ml-explore/mlx-lm"
+
+
+# How long (seconds) before a seen repo can trigger again
+DEDUP_TTL = 3600  # 1 hour
+
+
+def extract_repo_info(url: str) -> RepoInfo | None:
+    """Extract repository info from a URL if it matches a known source/registry site."""
+
+    # GitHub: github.com/<org>/<repo>/...
+    match = re.match(r"https?://github\.com/([^/]+)/([^/]+)", url)
+    if match:
+        org, repo = match.group(1), match.group(2)
+        # Strip .git suffix if present
+        repo = re.sub(r"\.git$", "", repo)
+        canonical = f"https://github.com/{org}/{repo}"
+        return RepoInfo(
+            canonical_url=canonical,
+            name=repo,
+            command=f"/bluera-knowledge:add-repo {canonical}",
+        )
+
+    # raw.githubusercontent.com/<org>/<repo>/...
+    match = re.match(r"https?://raw\.githubusercontent\.com/([^/]+)/([^/]+)", url)
+    if match:
+        org, repo = match.group(1), match.group(2)
+        canonical = f"https://github.com/{org}/{repo}"
+        return RepoInfo(
+            canonical_url=canonical,
+            name=repo,
+            command=f"/bluera-knowledge:add-repo {canonical}",
+        )
+
+    # PyPI: pypi.org/project/<package>/...
+    match = re.match(r"https?://pypi\.org/project/([^/]+)", url)
+    if match:
+        name = match.group(1).rstrip("/")
+        return RepoInfo(
+            canonical_url=f"https://pypi.org/project/{name}",
+            name=name,
+            command=f"/bluera-knowledge:add-repo {name}",
+        )
+
+    # npm: (www.)npmjs.com/package/<package>/...
+    match = re.match(r"https?://(?:www\.)?npmjs\.com/package/(@?[^/]+(?:/[^/]+)?)", url)
+    if match:
+        name = match.group(1)
+        return RepoInfo(
+            canonical_url=f"https://www.npmjs.com/package/{name}",
+            name=name,
+            command=f"/bluera-knowledge:add-repo {name}",
+        )
+
+    # crates.io: crates.io/crates/<crate>/...
+    match = re.match(r"https?://crates\.io/crates/([^/]+)", url)
+    if match:
+        name = match.group(1)
+        return RepoInfo(
+            canonical_url=f"https://crates.io/crates/{name}",
+            name=name,
+            command=f"/bluera-knowledge:add-repo {name}",
+        )
+
+    # pkg.go.dev: pkg.go.dev/<module>
+    match = re.match(r"https?://pkg\.go\.dev/(.+?)(?:\?|$|#)", url)
+    if match:
+        module = match.group(1).rstrip("/")
+        return RepoInfo(
+            canonical_url=f"https://pkg.go.dev/{module}",
+            name=module.split("/")[-1],
+            command=f"/bluera-knowledge:add-repo {module}",
+        )
+
+    # docs.rs: docs.rs/<crate>/...
+    match = re.match(r"https?://docs\.rs/([^/]+)", url)
+    if match:
+        name = match.group(1)
+        return RepoInfo(
+            canonical_url=f"https://docs.rs/{name}",
+            name=name,
+            command=f"/bluera-knowledge:add-repo {name}",
+        )
+
+    # readthedocs: <project>.readthedocs.io/...
+    match = re.match(r"https?://([^.]+)\.readthedocs\.io", url)
+    if match:
+        name = match.group(1)
+        return RepoInfo(
+            canonical_url=f"https://{name}.readthedocs.io",
+            name=name,
+            command=f"/bluera-knowledge:crawl https://{name}.readthedocs.io",
+        )
+
+    return None
+
+
+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-web-research-{h}.json"
+
+
+def is_already_seen(repo_key: str, project_root: str) -> bool:
+    """Check if this repo 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(repo_key, 0)
+        return (time.time() - ts) < DEDUP_TTL
+    except Exception:
+        return False
+
+
+def mark_seen(repo_key: str, project_root: str) -> None:
+    """Record this repo 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
+        # Prune expired
+        seen = {k: v for k, v in seen.items() if (now - v) < DEDUP_TTL}
+        seen[repo_key] = now
+        with open(path, "w") as f:
+            json.dump(seen, f)
+    except Exception:
+        pass  # Never fail
+
+
+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", "")
+        tool_input = hook_input.get("tool_input", {})
+
+        if tool_name != "WebFetch":
+            return 0
+
+        url = tool_input.get("url", "")
+        if not url:
+            return 0
+
+        info = extract_repo_info(url)
+        if not info:
+            return 0
+
+        project_root = os.environ.get("PROJECT_ROOT", os.environ.get("PWD", ""))
+
+        if is_already_seen(info["canonical_url"], project_root):
+            return 0
+
+        mark_seen(info["canonical_url"], project_root)
+
+        message = (
+            f"MANDATORY: You fetched documentation from {info['name']}.\n"
+            f"If this library will be used in the project, index it BEFORE continuing:\n"
+            f"  {info['command']}\n"
+            f"This gives you authoritative, searchable access instead of raw web fetches."
+        )
+
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": message,
+            }
+        }
+        print(json.dumps(output))
+        return 0
+
+    except Exception:
+        return 0  # Never fail on errors
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())