bluera-knowledge 0.31.0 → 0.33.0

package/scripts/setup.sh

@@ -0,0 +1,224 @@
+#!/bin/bash
+# Bluera Knowledge Plugin - Setup Script
+# Runs on: SessionStart (via auto-setup.sh) or manually
+#
+# Installs:
+#   - MCP wrapper script (bluera-knowledge-mcp)
+#   - Node.js dependencies (bun install / npm ci)
+#   - Playwright Chromium browser (for web crawling)
+#
+# Environment variables:
+#   NONINTERACTIVE=1 - Skip interactive prompts (for auto-setup)
+
+set -e
+
+# Get the plugin root directory
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$0")")}"
+
+# Non-interactive mode (set by auto-setup.sh)
+NONINTERACTIVE="${NONINTERACTIVE:-}"
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+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\":\"setup.sh\",\"msg\":\"$msg\"}" >> "$LOG_FILE" 2>/dev/null || true
+}
+
+log_debug "Setup starting, PLUGIN_ROOT=$PLUGIN_ROOT, PROJECT_ROOT=${PROJECT_ROOT:-unset}"
+
+echo -e "${YELLOW}[bluera-knowledge] Running setup...${NC}"
+
+# =====================
+# Node.js Dependencies
+# =====================
+
+log_debug "Checking node_modules at $PLUGIN_ROOT/node_modules"
+
+# =====================
+# Build Tools Check (required for native modules)
+# =====================
+
+log_debug "Checking build tools"
+
+if command -v make &> /dev/null; then
+    log_debug "make found"
+    echo -e "${GREEN}[bluera-knowledge] Build tools available ✓${NC}"
+else
+    log_debug "make not found, prompting for install"
+    echo -e "${YELLOW}[bluera-knowledge] Build tools (make) not found - required for native modules${NC}"
+
+    # Detect platform and set install command
+    if [ -f /etc/debian_version ]; then
+        INSTALL_CMD="sudo apt update && sudo apt install -y build-essential"
+        PLATFORM="Debian/Ubuntu"
+    elif [ -f /etc/fedora-release ] || [ -f /etc/redhat-release ]; then
+        INSTALL_CMD="sudo dnf groupinstall -y 'Development Tools'"
+        PLATFORM="Fedora/RHEL"
+    elif [ "$(uname)" = "Darwin" ]; then
+        INSTALL_CMD="xcode-select --install"
+        PLATFORM="macOS"
+    else
+        # Unknown platform - show manual instructions and exit
+        echo -e "${RED}[bluera-knowledge] Could not detect platform for auto-install${NC}"
+        echo -e "${YELLOW}Please install build tools manually:${NC}"
+        echo -e "${YELLOW}  Debian/Ubuntu: sudo apt install build-essential${NC}"
+        echo -e "${YELLOW}  Fedora/RHEL:   sudo dnf groupinstall 'Development Tools'${NC}"
+        echo -e "${YELLOW}  macOS:         xcode-select --install${NC}"
+        exit 1
+    fi
+
+    echo -e "${YELLOW}Detected platform: ${PLATFORM}${NC}"
+    echo -e "${YELLOW}Install command: ${INSTALL_CMD}${NC}"
+    echo ""
+
+    # Non-interactive mode: cannot prompt for sudo, exit with instructions
+    if [[ -n "$NONINTERACTIVE" ]]; then
+        log_debug "Non-interactive mode, cannot prompt for build tools install"
+        echo -e "${RED}[bluera-knowledge] Build tools required but running non-interactively.${NC}"
+        echo -e "${YELLOW}Run manually: ${INSTALL_CMD}${NC}"
+        echo -e "${YELLOW}Then restart Claude Code.${NC}"
+        exit 1
+    fi
+
+    read -p "Install build tools now? [y/N] " -n 1 -r
+    echo ""
+
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        log_debug "User confirmed install, running: $INSTALL_CMD"
+        echo -e "${YELLOW}[bluera-knowledge] Installing build tools...${NC}"
+        if eval "$INSTALL_CMD"; then
+            log_debug "Build tools installed successfully"
+            echo -e "${GREEN}[bluera-knowledge] Build tools installed ✓${NC}"
+        else
+            log_debug "Build tools install failed"
+            echo -e "${RED}[bluera-knowledge] Build tools installation failed${NC}"
+            echo -e "${YELLOW}Please install manually and retry${NC}"
+            exit 1
+        fi
+    else
+        log_debug "User declined install"
+        echo -e "${YELLOW}[bluera-knowledge] Skipped. Please install build tools manually:${NC}"
+        echo -e "${YELLOW}  ${INSTALL_CMD}${NC}"
+        exit 1
+    fi
+fi
+
+# =====================
+# MCP Wrapper Script
+# WORKAROUND: ${CLAUDE_PLUGIN_ROOT} not expanding in plugin .mcp.json
+# Claude Code's ${CLAUDE_PLUGIN_ROOT} should work per docs, but doesn't in some environments.
+# See: https://github.com/anthropics/claude-code/issues/9427
+# See: https://code.claude.com/docs/en/mcp (Plugin MCP configuration)
+# =====================
+
+log_debug "Installing MCP wrapper script"
+
+WRAPPER_DIR="$HOME/.local/bin"
+WRAPPER_PATH="$WRAPPER_DIR/bluera-knowledge-mcp"
+
+mkdir -p "$WRAPPER_DIR"
+cp "$PLUGIN_ROOT/scripts/mcp-wrapper.sh" "$WRAPPER_PATH"
+chmod +x "$WRAPPER_PATH"
+
+# Check if ~/.local/bin is in PATH
+if [[ ":$PATH:" != *":$WRAPPER_DIR:"* ]]; then
+    log_debug "Warning: $WRAPPER_DIR not in PATH"
+    echo -e "${YELLOW}[bluera-knowledge] Note: Add ~/.local/bin to your PATH if MCP server doesn't start${NC}"
+    echo -e "${YELLOW}  export PATH=\"\$HOME/.local/bin:\$PATH\"${NC}"
+fi
+
+echo -e "${GREEN}[bluera-knowledge] MCP wrapper installed ✓${NC}"
+
+# =====================
+# Node.js Dependencies
+# =====================
+
+if [ -d "$PLUGIN_ROOT/node_modules" ]; then
+    log_debug "node_modules exists, skipping install"
+    echo -e "${GREEN}[bluera-knowledge] Node.js dependencies already installed ✓${NC}"
+else
+    echo -e "${YELLOW}[bluera-knowledge] Installing Node.js dependencies...${NC}"
+
+    # Skip browser downloads during npm/bun install - browsers are installed separately below
+    export PUPPETEER_SKIP_DOWNLOAD=1
+    export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+
+    if command -v bun &> /dev/null; then
+        log_debug "Starting bun install --frozen-lockfile"
+        (cd "$PLUGIN_ROOT" && bun install --frozen-lockfile) && \
+            { log_debug "bun install complete"; echo -e "${GREEN}[bluera-knowledge] Node.js dependencies installed ✓${NC}"; } || \
+            { log_debug "bun install FAILED"; echo -e "${RED}[bluera-knowledge] Failed to install Node.js dependencies${NC}"; exit 1; }
+    elif command -v npm &> /dev/null; then
+        # CRITICAL: --legacy-peer-deps required!
+        # tree-sitter-go@0.25 requires tree-sitter@^0.25
+        # tree-sitter-rust@0.24 requires tree-sitter@^0.22
+        # These peer deps conflict - no compatible version exists.
+        # Without --legacy-peer-deps, npm fails even though tree-sitter is optional.
+        log_debug "Starting npm install --legacy-peer-deps"
+        (cd "$PLUGIN_ROOT" && npm install --legacy-peer-deps) && \
+            { log_debug "npm install complete"; echo -e "${GREEN}[bluera-knowledge] Node.js dependencies installed ✓${NC}"; } || \
+            { log_debug "npm install FAILED"; echo -e "${RED}[bluera-knowledge] Failed to install Node.js dependencies${NC}"; exit 1; }
+    else
+        log_debug "Neither bun nor npm found"
+        echo -e "${RED}[bluera-knowledge] Neither bun nor npm found${NC}"
+        exit 1
+    fi
+fi
+
+# =====================
+# Playwright Browser
+# =====================
+
+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 exists, skipping install"
+    echo -e "${GREEN}[bluera-knowledge] Playwright Chromium already installed ✓${NC}"
+else
+    echo -e "${YELLOW}[bluera-knowledge] Installing Playwright Chromium browser...${NC}"
+
+    log_debug "Starting npx playwright install chromium (this can take several minutes)"
+    if (cd "$PLUGIN_ROOT" && npx playwright install chromium); then
+        log_debug "Playwright install complete"
+        echo -e "${GREEN}[bluera-knowledge] Playwright Chromium installed ✓${NC}"
+    else
+        log_debug "Playwright install FAILED"
+        echo -e "${RED}[bluera-knowledge] Playwright browser install failed${NC}"
+        echo -e "${YELLOW}Manual fix: npx playwright install chromium${NC}"
+        exit 1
+    fi
+fi
+
+# =====================
+# Python3 Check (Optional)
+# =====================
+
+log_debug "Checking python3"
+
+if command -v python3 &> /dev/null; then
+    python_version=$(python3 -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
+    log_debug "Python $python_version found"
+    echo -e "${GREEN}[bluera-knowledge] Python ${python_version} available (for code-graph) ✓${NC}"
+else
+    log_debug "Python3 not found"
+    echo -e "${YELLOW}[bluera-knowledge] Python3 not found - code-graph feature unavailable${NC}"
+fi
+
+log_debug "Setup complete"
+echo -e "${GREEN}[bluera-knowledge] Setup complete ✓${NC}"

package/scripts/statusline-module.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# bluera-knowledge statusline module
+# Injected into ~/.claude/statusline.sh between boundary comments:
+#   # --- bluera-knowledge ---
+#   # --- end bluera-knowledge ---
+#
+# Expected variables from parent script:
+#   PROJECT_DIR - project directory path (from statusline JSON input)
+#
+# Exports:
+#   BK_STATUS - formatted status string (e.g. " 📘●3")
+
+get_bk_status() {
+    local project_dir="$1"
+    local store_count=""
+    local config_file="$project_dir/.bluera/bluera-knowledge/stores.config.json"
+    if [ -f "$config_file" ]; then
+        store_count=$(jq '.stores | length' "$config_file" 2>/dev/null)
+        [ "$store_count" = "0" ] && store_count=""
+    fi
+
+    if pgrep -f "bluera-knowledge.*bootstrap" >/dev/null 2>&1 || \
+       pgrep -f "bluera-knowledge-mcp" >/dev/null 2>&1; then
+        printf " 📘\033[32m●\033[0m%s" "$store_count"
+    else
+        printf " 📘\033[31m●\033[0m%s" "$store_count"
+    fi
+}
+BK_STATUS=$(get_bk_status "$PROJECT_DIR")

package/scripts/test-mcp-dev.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/**
+ * MCP Development Test Helper
+ *
+ * Spawns the MCP server and communicates with it directly via JSON-RPC over stdio.
+ * Used by test-plugin --dev to test MCP functionality without needing the plugin installed.
+ *
+ * Usage:
+ *   ./scripts/test-mcp-dev.mjs call <tool-name> '<json-args>'
+ *   ./scripts/test-mcp-dev.mjs call execute '{"command":"help"}'
+ *   ./scripts/test-mcp-dev.mjs call search '{"query":"test"}'
+ */
+
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = join(__dirname, '..');
+
+class MCPTestClient {
+  constructor() {
+    this.server = null;
+    this.messageId = 0;
+    this.pendingRequests = new Map();
+    this.initialized = false;
+  }
+
+  async start() {
+    return new Promise((resolve, reject) => {
+      const serverPath = join(PROJECT_ROOT, 'dist', 'mcp', 'server.js');
+
+      this.server = spawn('node', [serverPath], {
+        cwd: PROJECT_ROOT,
+        env: {
+          ...process.env,
+          PROJECT_ROOT: PROJECT_ROOT,
+          DATA_DIR: '.bluera/bluera-knowledge/data',
+          CONFIG_PATH: '.bluera/bluera-knowledge/config.json',
+        },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+
+      // Handle stderr (logs)
+      this.server.stderr.on('data', (data) => {
+        // Suppress server logs in test output unless DEBUG
+        if (process.env.DEBUG) {
+          process.stderr.write(`[server] ${data}`);
+        }
+      });
+
+      // Handle stdout (JSON-RPC responses)
+      const rl = createInterface({ input: this.server.stdout });
+      rl.on('line', (line) => {
+        try {
+          const msg = JSON.parse(line);
+          if (msg.id !== undefined && this.pendingRequests.has(msg.id)) {
+            const { resolve, reject } = this.pendingRequests.get(msg.id);
+            this.pendingRequests.delete(msg.id);
+            if (msg.error) {
+              reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+            } else {
+              resolve(msg.result);
+            }
+          }
+        } catch {
+          // Not JSON or parse error - ignore
+        }
+      });
+
+      this.server.on('error', reject);
+      this.server.on('spawn', () => {
+        // Give server a moment to initialize
+        setTimeout(() => resolve(), 100);
+      });
+    });
+  }
+
+  async initialize() {
+    if (this.initialized) return;
+
+    // Send initialize request
+    const initResult = await this.sendRequest('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'test-mcp-dev', version: '1.0.0' },
+    });
+
+    // Send initialized notification
+    this.sendNotification('notifications/initialized', {});
+
+    this.initialized = true;
+    return initResult;
+  }
+
+  sendRequest(method, params) {
+    return new Promise((resolve, reject) => {
+      const id = ++this.messageId;
+      const request = { jsonrpc: '2.0', id, method, params };
+
+      this.pendingRequests.set(id, { resolve, reject });
+
+      // Set timeout for request
+      setTimeout(() => {
+        if (this.pendingRequests.has(id)) {
+          this.pendingRequests.delete(id);
+          reject(new Error(`Request timeout: ${method}`));
+        }
+      }, 30000);
+
+      this.server.stdin.write(JSON.stringify(request) + '\n');
+    });
+  }
+
+  sendNotification(method, params) {
+    const notification = { jsonrpc: '2.0', method, params };
+    this.server.stdin.write(JSON.stringify(notification) + '\n');
+  }
+
+  async callTool(name, args) {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+
+    const result = await this.sendRequest('tools/call', {
+      name,
+      arguments: args,
+    });
+
+    return result;
+  }
+
+  async listTools() {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+
+    return this.sendRequest('tools/list', {});
+  }
+
+  stop() {
+    if (this.server) {
+      this.server.kill('SIGTERM');
+      this.server = null;
+    }
+  }
+}
+
+// Session mode - reads multiple commands from stdin, maintains server across calls
+async function sessionMode() {
+  const client = new MCPTestClient();
+  await client.start();
+
+  const rl = createInterface({ input: process.stdin });
+  const results = [];
+  let lastResultId = null;
+
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const spaceIndex = trimmed.indexOf(' ');
+    const toolName = spaceIndex > 0 ? trimmed.slice(0, spaceIndex) : trimmed;
+    let argsStr = spaceIndex > 0 ? trimmed.slice(spaceIndex + 1) : '{}';
+
+    // Substitute $LAST_ID with actual result ID from previous search
+    if (lastResultId && argsStr.includes('$LAST_ID')) {
+      argsStr = argsStr.replace(/\$LAST_ID/g, lastResultId);
+    }
+
+    const args = JSON.parse(argsStr);
+    const result = await client.callTool(toolName, args);
+    results.push(result);
+
+    // Extract result ID for next call (search results have results[0].id)
+    // Search results have a header line before JSON, so find first '{'
+    if (result?.content?.[0]?.text) {
+      const text = result.content[0].text;
+      const jsonStart = text.indexOf('{');
+      if (jsonStart >= 0) {
+        try {
+          const parsed = JSON.parse(text.slice(jsonStart));
+          if (parsed.results?.[0]?.id) {
+            lastResultId = parsed.results[0].id;
+          }
+        } catch {
+          // Not valid JSON or no results - ignore
+        }
+      }
+    }
+  }
+
+  client.stop();
+  console.log(JSON.stringify(results, null, 2));
+}
+
+// CLI interface
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 1) {
+    console.error('Usage: test-mcp-dev.js <command> [args...]');
+    console.error('Commands:');
+    console.error('  call <tool-name> <json-args>  - Call an MCP tool (one-shot)');
+    console.error('  session                       - Read commands from stdin (persistent server)');
+    console.error('  list                          - List available tools');
+    console.error('');
+    console.error('Examples:');
+    console.error('  ./scripts/test-mcp-dev.js call execute \'{"command":"help"}\'');
+    console.error('  ./scripts/test-mcp-dev.js call search \'{"query":"test"}\'');
+    console.error('  ./scripts/test-mcp-dev.js list');
+    console.error('');
+    console.error('Session mode (maintains cache across calls):');
+    console.error('  echo -e \'search {"query":"test"}\\nget_full_context {"resultId":"$LAST_ID"}\' | ./scripts/test-mcp-dev.js session');
+    process.exit(1);
+  }
+
+  const command = args[0];
+
+  // Session mode handles its own client lifecycle
+  if (command === 'session') {
+    await sessionMode();
+    return;
+  }
+
+  const client = new MCPTestClient();
+
+  try {
+    await client.start();
+
+    if (command === 'call') {
+      if (args.length < 3) {
+        console.error('Usage: test-mcp-dev.js call <tool-name> <json-args>');
+        process.exit(1);
+      }
+
+      const toolName = args[1];
+      const toolArgs = JSON.parse(args[2]);
+
+      const result = await client.callTool(toolName, toolArgs);
+
+      // Output result as JSON for parsing by test-plugin
+      console.log(JSON.stringify(result, null, 2));
+    } else if (command === 'list') {
+      const result = await client.listTools();
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Unknown command: ${command}`);
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  } finally {
+    client.stop();
+  }
+}
+
+main();