bluera-knowledge 0.9.21

package/eslint-rules/require-skip-comment.js

@@ -0,0 +1,81 @@
+/**
+ * ESLint rule to require explanatory comments for skipped tests
+ *
+ * Enforces that any use of .skip (it.skip, describe.skip, test.skip)
+ * must have a comment immediately preceding it explaining why the test is skipped.
+ *
+ * Inspired by: https://github.com/cypress-io/eslint-plugin-dev/pull/15
+ */
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require explanatory comments for skipped tests',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    messages: {
+      missingComment: 'Skipped test must have a comment explaining why it is skipped',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    /**
+     * Check if a node is a skipped test (it.skip, describe.skip, test.skip)
+     */
+    function isSkippedTest(node) {
+      if (node.type !== 'CallExpression') {
+        return false;
+      }
+
+      const { callee } = node;
+
+      // Check for it.skip(), describe.skip(), test.skip()
+      if (callee.type === 'MemberExpression') {
+        const objectName = callee.object.name;
+        const propertyName = callee.property.name;
+
+        return (
+          (objectName === 'it' || objectName === 'describe' || objectName === 'test') &&
+          propertyName === 'skip'
+        );
+      }
+
+      return false;
+    }
+
+    /**
+     * Check if there's a comment immediately before the node
+     */
+    function hasCommentBefore(node) {
+      const comments = sourceCode.getCommentsBefore(node);
+
+      if (comments.length === 0) {
+        return false;
+      }
+
+      // Check if the last comment is on the line immediately before
+      const lastComment = comments[comments.length - 1];
+      const commentEndLine = lastComment.loc.end.line;
+      const nodeStartLine = node.loc.start.line;
+
+      // Comment should be on the line immediately before, or on the same line
+      return nodeStartLine - commentEndLine <= 1;
+    }
+
+    return {
+      CallExpression(node) {
+        if (isSkippedTest(node) && !hasCommentBefore(node)) {
+          context.report({
+            node,
+            messageId: 'missingComment',
+          });
+        }
+      },
+    };
+  },
+};

package/eslint.config.js

@@ -0,0 +1,61 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintComments from 'eslint-plugin-eslint-comments';
+import requireSkipComment from './eslint-rules/require-skip-comment.js';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    plugins: {
+      'eslint-comments': eslintComments,
+    },
+    rules: {
+      // Type safety
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-unsafe-assignment': 'error',
+      '@typescript-eslint/no-unsafe-member-access': 'error',
+      '@typescript-eslint/no-unsafe-call': 'error',
+      '@typescript-eslint/no-unsafe-return': 'error',
+      '@typescript-eslint/explicit-function-return-type': 'error',
+      '@typescript-eslint/explicit-module-boundary-types': 'error',
+      '@typescript-eslint/prefer-readonly': 'error',
+      '@typescript-eslint/strict-boolean-expressions': 'error',
+      '@typescript-eslint/consistent-type-assertions': ['error', { assertionStyle: 'never' }],
+
+      // Dead code detection
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      'no-unreachable': 'error',
+      'no-unreachable-loop': 'error',
+      'no-constant-condition': ['error', { checkLoops: false }],
+
+      // Require explanations for ESLint disable comments (warn for now to allow gradual fix)
+      'eslint-comments/require-description': 'warn',
+    },
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**', '*.config.js', '**/*.test.ts', 'tests/**/*.ts'],
+  },
+  // Test files: Apply custom skip-comment rule only
+  {
+    files: ['**/*.test.ts', 'tests/**/*.ts'],
+    plugins: {
+      'custom': {
+        rules: {
+          'require-skip-comment': requireSkipComment,
+        },
+      },
+    },
+    rules: {
+      'custom/require-skip-comment': 'error',
+    },
+  }
+);

package/hooks/check-dependencies.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# Bluera Knowledge Plugin - Dependency Checker
+# Automatically checks and installs dependencies for the plugin
+
+set -e
+
+# Get the plugin root directory
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$0")")}"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# =====================
+# Node.js Dependencies
+# =====================
+
+# Check if node_modules exists
+if [ ! -d "$PLUGIN_ROOT/node_modules" ]; then
+    echo -e "${YELLOW}[bluera-knowledge] Installing Node.js dependencies...${NC}"
+
+    # Try bun first (faster), fall back to npm
+    if command -v bun &> /dev/null; then
+        (cd "$PLUGIN_ROOT" && bun install --frozen-lockfile 2>/dev/null) && \
+            echo -e "${GREEN}[bluera-knowledge] Node.js dependencies installed ✓${NC}" || \
+            echo -e "${RED}[bluera-knowledge] Failed to install Node.js dependencies${NC}"
+    elif command -v npm &> /dev/null; then
+        (cd "$PLUGIN_ROOT" && npm ci --silent 2>/dev/null) && \
+            echo -e "${GREEN}[bluera-knowledge] Node.js dependencies installed ✓${NC}" || \
+            echo -e "${RED}[bluera-knowledge] Failed to install Node.js dependencies${NC}"
+    else
+        echo -e "${RED}[bluera-knowledge] Neither bun nor npm found. Please install Node.js dependencies manually.${NC}"
+    fi
+fi
+
+# =====================
+# Python Dependencies
+# =====================
+
+# Check if Python3 is installed
+if ! command -v python3 &> /dev/null; then
+    echo -e "${RED}[bluera-knowledge] Python3 is not installed${NC}"
+    echo -e "${YELLOW}Web crawling features require Python 3.x${NC}"
+    echo -e "${YELLOW}Install Python3: https://www.python.org/downloads/${NC}"
+    exit 0  # Don't block the session, just warn
+fi
+
+# Check Python version (require 3.8+)
+python_version=$(python3 -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
+required_version="3.8"
+
+if ! python3 -c "import sys; exit(0 if sys.version_info >= (3, 8) else 1)"; then
+    echo -e "${YELLOW}[bluera-knowledge] Python ${python_version} detected. Python 3.8+ recommended for crawl4ai${NC}"
+fi
+
+# Check if crawl4ai is installed
+if python3 -c "import crawl4ai" 2>/dev/null; then
+    # Already installed - get version
+    crawl4ai_version=$(python3 -c "import crawl4ai; print(crawl4ai.__version__)" 2>/dev/null || echo "unknown")
+    echo -e "${GREEN}[bluera-knowledge] crawl4ai ${crawl4ai_version} is installed ✓${NC}"
+    exit 0
+fi
+
+# crawl4ai not installed - attempt installation
+echo -e "${YELLOW}[bluera-knowledge] crawl4ai not found. Web crawling features will be unavailable.${NC}"
+echo ""
+echo -e "${YELLOW}To enable web crawling, install crawl4ai:${NC}"
+echo -e "  ${GREEN}pip install crawl4ai${NC}"
+echo ""
+
+# Check if we should auto-install
+if command -v pip3 &> /dev/null || command -v pip &> /dev/null; then
+    echo -e "${YELLOW}Attempting automatic installation via pip...${NC}"
+
+    # Try to install using pip3 or pip
+    if command -v pip3 &> /dev/null; then
+        PIP_CMD="pip3"
+    else
+        PIP_CMD="pip"
+    fi
+
+    # Try with --break-system-packages for PEP 668 environments (Python 3.11+)
+    # This is needed on modern Python versions (macOS Homebrew, some Linux distros)
+    if $PIP_CMD install --quiet --break-system-packages crawl4ai 2>/dev/null; then
+        echo -e "${GREEN}[bluera-knowledge] Successfully installed crawl4ai ✓${NC}"
+        crawl4ai_version=$(python3 -c "import crawl4ai; print(crawl4ai.__version__)" 2>/dev/null || echo "installed")
+        echo -e "${GREEN}[bluera-knowledge] crawl4ai ${crawl4ai_version} ready${NC}"
+    else
+        # Fallback: try without --break-system-packages for older Python
+        if $PIP_CMD install --quiet --user crawl4ai 2>/dev/null; then
+            echo -e "${GREEN}[bluera-knowledge] Successfully installed crawl4ai ✓${NC}"
+            crawl4ai_version=$(python3 -c "import crawl4ai; print(crawl4ai.__version__)" 2>/dev/null || echo "installed")
+            echo -e "${GREEN}[bluera-knowledge] crawl4ai ${crawl4ai_version} ready${NC}"
+        else
+            echo -e "${RED}[bluera-knowledge] Auto-installation failed${NC}"
+            echo ""
+            echo -e "${YELLOW}For Python 3.11+ (externally-managed), install manually:${NC}"
+            echo -e "  ${GREEN}pip install --break-system-packages crawl4ai${NC}"
+            echo -e "${YELLOW}Or use a virtual environment:${NC}"
+            echo -e "  ${GREEN}python3 -m venv venv && source venv/bin/activate && pip install crawl4ai${NC}"
+        fi
+    fi
+else
+    echo -e "${YELLOW}pip not found. Please install crawl4ai manually.${NC}"
+fi
+
+# Always exit 0 to not block the session
+exit 0

package/hooks/format-search-results.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""
+PostToolUse hook to format mcp__bluera-knowledge__search results
+into a fixed-width table with deterministic output.
+"""
+
+import json
+import sys
+import os
+
+# Column widths (content only, not including | separators)
+SCORE_WIDTH = 6   # Right-aligned: " 1.00 "
+STORE_WIDTH = 12  # Left-aligned: "store       "
+FILE_WIDTH = 45   # Left-aligned: "path/to/file..."
+PURPOSE_WIDTH = 48  # Left-aligned: "Purpose text..."
+
+
+def truncate(text: str, max_len: int) -> str:
+    """Truncate text with ellipsis if needed."""
+    if len(text) <= max_len:
+        return text
+    return text[:max_len - 3] + "..."
+
+
+def format_score(score: float) -> str:
+    """Format score as right-aligned fixed-width string."""
+    return f"{score:5.2f}".rjust(SCORE_WIDTH)
+
+
+def format_store(store_name: str) -> str:
+    """Format store name as left-aligned fixed-width string."""
+    truncated = truncate(store_name, STORE_WIDTH)
+    return truncated.ljust(STORE_WIDTH)
+
+
+def format_file(location: str, repo_root: str) -> str:
+    """Format file path as left-aligned fixed-width string."""
+    # Strip repo root prefix
+    if repo_root and location.startswith(repo_root):
+        path = location[len(repo_root):].lstrip("/")
+    else:
+        path = location
+    truncated = truncate(path, FILE_WIDTH)
+    return truncated.ljust(FILE_WIDTH)
+
+
+def format_purpose(purpose: str) -> str:
+    """Format purpose as left-aligned fixed-width string."""
+    # Clean up purpose text
+    clean = purpose.replace("\n", " ").strip()
+    truncated = truncate(clean, PURPOSE_WIDTH)
+    return truncated.ljust(PURPOSE_WIDTH)
+
+
+def format_table(results: list, query: str) -> str:
+    """Format search results into a fixed-width markdown table."""
+    lines = []
+
+    # Header
+    lines.append(f"## Search Results for \"{query}\"")
+    lines.append("")
+
+    if not results:
+        lines.append(f"No results found for \"{query}\"")
+        lines.append("")
+        lines.append("Try:")
+        lines.append("- Broadening your search terms")
+        lines.append("- Checking if the relevant stores are indexed")
+        lines.append("- Using /bluera-knowledge:stores to see available stores")
+        return "\n".join(lines)
+
+    # Table header
+    header = f"| {'Score'.rjust(SCORE_WIDTH)} | {'Store'.ljust(STORE_WIDTH)} | {'File'.ljust(FILE_WIDTH)} | {'Purpose'.ljust(PURPOSE_WIDTH)} |"
+    # Separator: Score is right-aligned (colon at end), others are left-aligned
+    # The +2 accounts for the spaces around content, -1 for the colon on Score column
+    separator = f"|{'-' * (SCORE_WIDTH + 1)}:|{'-' * (STORE_WIDTH + 2)}|{'-' * (FILE_WIDTH + 2)}|{'-' * (PURPOSE_WIDTH + 2)}|"
+
+    lines.append(header)
+    lines.append(separator)
+
+    # Data rows
+    for result in results:
+        score = result.get("score", 0)
+        summary = result.get("summary", {})
+        store_name = summary.get("storeName", "unknown")
+        location = summary.get("location", "")
+        repo_root = summary.get("repoRoot", "")
+        purpose = summary.get("purpose", "")
+
+        row = f"| {format_score(score)} | {format_store(store_name)} | {format_file(location, repo_root)} | {format_purpose(purpose)} |"
+        lines.append(row)
+
+    lines.append("")
+    lines.append(f"**Found**: {len(results)} results")
+
+    return "\n".join(lines)
+
+
+def main():
+    try:
+        # Read hook input from stdin
+        input_data = json.load(sys.stdin)
+
+        tool_name = input_data.get("tool_name", "")
+        tool_input = input_data.get("tool_input", {})
+        tool_result = input_data.get("tool_result", {})
+
+        # Only process search results
+        if tool_name != "mcp__bluera-knowledge__search":
+            sys.exit(0)
+
+        # Extract results and query
+        results = tool_result.get("results", [])
+        query = tool_input.get("query", "")
+
+        # Format the table
+        formatted = format_table(results, query)
+
+        # Output the formatted table
+        # For PostToolUse, stdout is shown in the transcript
+        print(formatted)
+
+    except json.JSONDecodeError as e:
+        print(f"Error parsing hook input: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error formatting results: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "description": "bluera-knowledge plugin hooks - automatic dependency checking and job status monitoring",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/check-dependencies.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/job-status-hook.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

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/knip.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": [
+    "src/**/*.test.ts",
+    "tests/**/*.test.ts"
+  ],
+  "project": [
+    "src/**/*.ts",
+    "tests/**/*.ts"
+  ],
+  "ignore": [
+    "dist/**",
+    "coverage/**",
+    "node_modules/**",
+    ".husky/**",
+    "tests/fixtures/**",
+    "tests/helpers/**",
+    "src/cli/index.ts",
+    "src/db/index.ts",
+    "src/types/index.ts"
+  ],
+  "ignoreDependencies": [
+    "@types/*",
+    "husky",
+    "tsup",
+    "tsx",
+    "chalk",
+    "cli-table3",
+    "ora",
+    "commander",
+    "node-addon-api",
+    "slurp-ai",
+    "node-gyp"
+  ],
+  "ignoreExportsUsedInFile": {
+    "interface": true,
+    "type": true
+  },
+  "vitest": {
+    "config": ["vitest.config.ts"],
+    "entry": ["vitest.config.ts"]
+  }
+}

package/mcp.plugin.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "bluera-knowledge": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"],
+      "env": {
+        "DATA_DIR": ".bluera/bluera-knowledge/data",
+        "CONFIG_PATH": ".bluera/bluera-knowledge/config.json"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "bluera-knowledge",
+  "version": "0.9.21",
+  "description": "CLI tool for managing knowledge stores with semantic search",
+  "type": "module",
+  "bin": {
+    "bluera-knowledge": "./dist/index.js",
+    "bluera-knowledge-worker": "./dist/workers/background-worker-cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "lint:deadcode": "knip --no-exit-code",
+    "lint:deadcode:strict": "knip",
+    "typecheck": "tsc --noEmit",
+    "precommit": ".husky/pre-commit",
+    "prepush": ".husky/pre-push",
+    "lint:quiet": "eslint src/ --quiet && echo '✓ Lint passed' || { echo '❌ ESLint errors'; exit 1; }",
+    "lint:deadcode:quiet": "knip --no-exit-code --quiet 2>&1 | grep -E '^(Unused|Configuration)' || echo '✓ No unused code'",
+    "typecheck:quiet": "tsc --noEmit --pretty false && echo '✓ Type check passed'",
+    "test:changed:quiet": "vitest run --changed --reporter=dot --silent 2>&1 | tail -3",
+    "test:coverage:quiet": "vitest run --coverage --reporter=dot 2>&1 | grep -E '(FAIL|Test Files|passed|Coverage|threshold)' | tail -10",
+    "build:quiet": "tsup --silent && echo '✓ Build complete'",
+    "prepare": "husky",
+    "version:major": "commit-and-tag-version --release-as major --skip.commit --skip.tag",
+    "version:minor": "commit-and-tag-version --release-as minor --skip.commit --skip.tag",
+    "version:patch": "commit-and-tag-version --release-as patch --skip.commit --skip.tag",
+    "release:patch": "commit-and-tag-version --release-as patch && git push --follow-tags",
+    "release:minor": "commit-and-tag-version --release-as minor && git push --follow-tags",
+    "release:major": "commit-and-tag-version --release-as major && git push --follow-tags"
+  },
+  "keywords": [
+    "knowledge",
+    "semantic-search",
+    "vector-database",
+    "cli"
+  ],
+  "author": "Bluera",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blueraai/bluera-knowledge.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/babel__core": "^7.20.5",
+    "@types/babel__traverse": "^7.28.0",
+    "@types/node": "^25.0.2",
+    "@types/turndown": "^5.0.6",
+    "@vitest/coverage-v8": "^4.0.16",
+    "commit-and-tag-version": "^12.6.1",
+    "eslint": "^9.39.2",
+    "eslint-plugin-eslint-comments": "^3.2.0",
+    "husky": "^9.1.7",
+    "knip": "^5.79.0",
+    "node-gyp": "^12.1.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.0",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.28.5",
+    "@babel/traverse": "^7.28.5",
+    "@babel/types": "^7.28.5",
+    "@extractus/article-extractor": "^8.0.20",
+    "@hono/node-server": "^1.19.7",
+    "@huggingface/transformers": "^3.8.1",
+    "@lancedb/lancedb": "^0.23.0",
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "apache-arrow": "^21.1.0",
+    "axios": "^1.13.2",
+    "chalk": "^5.6.2",
+    "cheerio": "^1.1.2",
+    "chokidar": "^5.0.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.2",
+    "hono": "^4.11.1",
+    "node-addon-api": "^8.5.0",
+    "ora": "^9.0.0",
+    "slurp-ai": "^1.0.6",
+    "tree-sitter": "^0.25.0",
+    "tree-sitter-go": "^0.23.1",
+    "tree-sitter-rust": "^0.24.0",
+    "turndown": "^7.2.2",
+    "turndown-plugin-gfm": "^1.0.2",
+    "zod": "^4.3.4"
+  }
+}