bluera-knowledge 0.11.20 → 0.12.1

package/dist/mcp/server.js

@@ -1,8 +1,8 @@
 import {
   createMCPServer,
   runMCPServer
-} from "../chunk-ZSKQIMD7.js";
-import "../chunk-MQGRQ2EG.js";
+} from "../chunk-CC6EGZ4D.js";
+import "../chunk-C4SYGLAI.js";
 import "../chunk-HRQD3MPH.js";
 export {
   createMCPServer,

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   IntelligentCrawler
-} from "../chunk-Q2ZGPJ66.js";
+} from "../chunk-QCSFBMYW.js";
 import {
   JobService,
   createDocumentId,
@@ -9,7 +9,7 @@ import {
   createServices,
   createStoreId,
   shutdownLogger
-} from "../chunk-MQGRQ2EG.js";
+} from "../chunk-C4SYGLAI.js";
 import "../chunk-HRQD3MPH.js";
 
 // src/workers/background-worker.ts

package/hooks/hooks.json

@@ -1,6 +1,28 @@
 {
-  "description": "bluera-knowledge plugin hooks - automatic dependency checking and job status monitoring",
+  "description": "bluera-knowledge plugin hooks - dependency checking, job monitoring, and BK suggestions",
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse-bk-reminder.py",
+            "timeout": 3
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse-bk-reminder.py",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "hooks": [
@@ -19,6 +41,11 @@
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/job-status-hook.sh",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/skill-activation.py",
+            "timeout": 5
           }
         ]
       }

package/hooks/pretooluse-bk-reminder.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+PreToolUse hook for bluera-knowledge plugin.
+Fires when Claude is about to Grep/Read in dependency directories,
+reminding to consider using BK instead.
+"""
+
+import json
+import re
+import sys
+from typing import Any
+
+# Patterns indicating library/dependency code
+LIBRARY_PATH_PATTERNS = [
+    r"node_modules/",
+    r"vendor/",
+    r"site-packages/",
+    r"\.venv/",
+    r"venv/",
+    r"bower_components/",
+    r"packages/.*/node_modules/",
+    r"\.npm/",
+    r"\.cargo/registry/",
+    r"go/pkg/mod/",
+]
+
+# Compile patterns for efficiency
+LIBRARY_PATTERNS_RE = re.compile("|".join(LIBRARY_PATH_PATTERNS), re.IGNORECASE)
+
+
+def check_grep_tool(tool_input: dict[str, Any]) -> str | None:
+    """Check if Grep is targeting library code."""
+    path = tool_input.get("path", "")
+    pattern = tool_input.get("pattern", "")
+
+    # Check if searching in library directories
+    if path and LIBRARY_PATTERNS_RE.search(path):
+        return f"grep in `{path}`"
+
+    # Check if pattern suggests library-specific search
+    # (searching for common library internals)
+    return None
+
+
+def check_read_tool(tool_input: dict[str, Any]) -> str | None:
+    """Check if Read is targeting library code."""
+    file_path = tool_input.get("file_path", "")
+
+    if file_path and LIBRARY_PATTERNS_RE.search(file_path):
+        return f"read `{file_path}`"
+
+    return None
+
+
+def main() -> int:
+    try:
+        stdin_data = sys.stdin.read()
+        if not stdin_data.strip():
+            return 0
+        hook_input = json.loads(stdin_data)
+    except json.JSONDecodeError:
+        return 0
+
+    tool_name = hook_input.get("tool_name", "")
+    tool_input = hook_input.get("tool_input", {})
+
+    trigger_reason = None
+
+    if tool_name == "Grep":
+        trigger_reason = check_grep_tool(tool_input)
+    elif tool_name == "Read":
+        trigger_reason = check_read_tool(tool_input)
+
+    if not trigger_reason:
+        return 0
+
+    # Output reminder
+    reminder = f"""<system-reminder>
+BLUERA-KNOWLEDGE SUGGESTION
+
+You're about to {trigger_reason} which appears to be dependency/library code.
+
+Consider querying Bluera Knowledge instead:
+- Use MCP tool `search` with a relevant query
+- Or invoke `/bluera-knowledge:search <query>`
+
+BK provides indexed, searchable access to library sources - faster and more context-efficient than grepping through node_modules.
+
+If you don't have this library indexed, continue with your current approach.
+</system-reminder>"""
+
+    print(reminder)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/skill-activation.py

@@ -0,0 +1,190 @@
+#!/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
+
+CONFIG_DIR = Path.home() / ".local" / "share" / "bluera-knowledge"
+CONFIG_FILE = CONFIG_DIR / "skill-activation.json"
+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 load_config() -> dict[str, Any]:
+    """Load skill activation configuration."""
+    if not CONFIG_FILE.exists():
+        return DEFAULT_CONFIG.copy()
+    try:
+        with open(CONFIG_FILE, 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 the system-reminder for matched skills."""
+    lines = [
+        "<system-reminder>",
+        "BLUERA-KNOWLEDGE SKILL ACTIVATION",
+        "",
+        "The user's prompt suggests they may benefit from these skills.",
+        "For EACH skill below, decide YES/NO:",
+        "- YES: Invoke via Skill tool: Skill(skill='bluera-knowledge:<skill-name>')",
+        "- NO: Skip (user doesn't need this guidance)",
+        "",
+        "Candidate skills (ranked by relevance):",
+    ]
+
+    for name, score, reasons, description in matches:
+        lines.append(f"")
+        lines.append(f"  [{name}] (score={score})")
+        lines.append(f"  Purpose: {description}")
+        lines.append(f"  Matched: {', '.join(reasons[:3])}")
+
+    lines.append("")
+    lines.append("Evaluate quickly, then answer the user's question.")
+    lines.append("</system-reminder>")
+
+    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
+    reminder = generate_reminder(matches)
+    print(reminder)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/skill-rules.json

@@ -0,0 +1,122 @@
+{
+  "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 }
+      ],
+      "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" }
+      ]
+    },
+    {
+      "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)" }
+      ]
+    }
+  ]
+}

package/package.json

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

package/src/analysis/code-graph.test.ts

@@ -328,6 +328,36 @@ describe('CodeGraph', () => {
       expect(edgeTypes).toContain('calls');
     });
 
+    it('includes confidence in serialized edges', () => {
+      const graph = new CodeGraph();
+      const nodes: CodeNode[] = [
+        {
+          type: 'function',
+          name: 'fn',
+          exported: false,
+          startLine: 1,
+          endLine: 2,
+        },
+      ];
+
+      graph.addNodes(nodes, '/src/test.ts');
+      graph.addImport('/src/test.ts', 'module', ['util']); // confidence: 1.0
+      graph.analyzeCallRelationships('other();', '/src/test.ts', 'fn'); // confidence: 0.5
+
+      const json = graph.toJSON();
+
+      // All edges should have confidence property preserved
+      expect(json.edges.every((e) => typeof e.confidence === 'number')).toBe(true);
+
+      // Import edges have confidence 1.0
+      const importEdge = json.edges.find((e) => e.type === 'imports');
+      expect(importEdge?.confidence).toBe(1.0);
+
+      // Call edges from regex detection have confidence 0.5
+      const callEdge = json.edges.find((e) => e.type === 'calls');
+      expect(callEdge?.confidence).toBe(0.5);
+    });
+
     it('handles empty graph', () => {
       const graph = new CodeGraph();
       const json = graph.toJSON();

package/src/analysis/code-graph.ts

@@ -227,7 +227,10 @@ export class CodeGraph {
     return importPath;
   }
 
-  toJSON(): { nodes: GraphNode[]; edges: Array<{ from: string; to: string; type: string }> } {
+  toJSON(): {
+    nodes: GraphNode[];
+    edges: Array<{ from: string; to: string; type: string; confidence: number }>;
+  } {
     const allEdges: GraphEdge[] = [];
     for (const edges of this.edges.values()) {
       allEdges.push(...edges);
@@ -235,7 +238,12 @@ export class CodeGraph {
 
     return {
       nodes: Array.from(this.nodes.values()),
-      edges: allEdges.map((e) => ({ from: e.from, to: e.to, type: e.type })),
+      edges: allEdges.map((e) => ({
+        from: e.from,
+        to: e.to,
+        type: e.type,
+        confidence: e.confidence,
+      })),
     };
   }
 }

package/src/cli/commands/store.test.ts

@@ -17,8 +17,23 @@ interface MockStoreService {
   delete: MockInstance;
 }
 
+interface MockLanceService {
+  deleteStore: MockInstance;
+}
+
+interface MockCodeGraphService {
+  deleteGraph: MockInstance;
+}
+
+interface MockConfigService {
+  resolveDataDir: MockInstance;
+}
+
 interface MockServices {
   store: MockStoreService;
+  lance: MockLanceService;
+  codeGraph: MockCodeGraphService;
+  config: MockConfigService;
 }
 
 describe('store command execution', () => {
@@ -38,6 +53,15 @@ describe('store command execution', () => {
         create: vi.fn(),
         delete: vi.fn(),
       },
+      lance: {
+        deleteStore: vi.fn().mockResolvedValue(undefined),
+      },
+      codeGraph: {
+        deleteGraph: vi.fn().mockResolvedValue(undefined),
+      },
+      config: {
+        resolveDataDir: vi.fn().mockReturnValue('/tmp/test-data'),
+      },
     };
 
     vi.mocked(createServices).mockResolvedValue(mockServices);
@@ -366,6 +390,51 @@ describe('store command execution', () => {
       });
     });
 
+    it('creates repo store with branch option', async () => {
+      const mockStore: RepoStore = {
+        id: createStoreId('new-store-6'),
+        name: 'branched-repo',
+        type: 'repo',
+        path: '/path/to/cloned/repo',
+        url: 'https://github.com/user/repo',
+        branch: 'develop',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      mockServices.store.create.mockResolvedValue({
+        success: true,
+        data: mockStore,
+      });
+
+      const command = createStoreCommand(getOptions);
+      const createCommand = command.commands.find((c) => c.name() === 'create');
+      const actionHandler = createCommand?._actionHandler;
+
+      createCommand.parseOptions([
+        '--type',
+        'repo',
+        '--source',
+        'https://github.com/user/repo',
+        '--branch',
+        'develop',
+      ]);
+      await actionHandler!(['branched-repo']);
+
+      expect(mockServices.store.create).toHaveBeenCalledWith({
+        name: 'branched-repo',
+        type: 'repo',
+        path: undefined,
+        url: 'https://github.com/user/repo',
+        branch: 'develop',
+        description: undefined,
+        tags: undefined,
+      });
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Created store: branched-repo')
+      );
+    });
+
     it('outputs JSON when format is json', async () => {
       const mockStore: FileStore = {
         id: createStoreId('new-store-5'),
@@ -860,6 +929,15 @@ describe('store command execution', () => {
       expect(tagsOption?.mandatory).toBe(false);
     });
 
+    it('create subcommand has --branch option for repo type', () => {
+      const command = createStoreCommand(getOptions);
+      const createCommand = command.commands.find((c) => c.name() === 'create');
+      const branchOption = createCommand?.options.find((o) => o.long === '--branch');
+
+      expect(branchOption).toBeDefined();
+      expect(branchOption?.mandatory).toBe(false);
+    });
+
     it('delete subcommand has force and yes options', () => {
       const command = createStoreCommand(getOptions);
       const deleteCommand = command.commands.find((c) => c.name() === 'delete');