bluera-knowledge 0.27.2 → 0.27.4

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.27.4](https://github.com/blueraai/bluera-knowledge/compare/v0.27.3...v0.27.4) (2026-02-10)
+
+
+### Bug Fixes
+
+* **gitignore:** add semantic equivalence, dedup, and managed section markers ([a07d6fe](https://github.com/blueraai/bluera-knowledge/commit/a07d6fe2bdf5214f8deee86b1c888eb318356809))
+* **plugin:** remove redundant hooks manifest entry ([6fa1e6f](https://github.com/blueraai/bluera-knowledge/commit/6fa1e6f1401464db2d2bd8d2929524b73bdc6a4b))
+
+## [0.27.3](https://github.com/blueraai/bluera-knowledge/compare/v0.27.2...v0.27.3) (2026-02-07)
+
 ## [0.27.2](https://github.com/blueraai/bluera-knowledge/compare/v0.27.1...v0.27.2) (2026-02-05)
 
 

package/README.md

@@ -452,200 +452,18 @@ Combine canonical library code with project-specific patterns:
 
 ## 🔧 Troubleshooting
 
-### Quick Diagnostics
-
-Run `/bluera-knowledge:doctor` to diagnose common issues. This checks:
-- Build tools (make/gcc) - required for native modules
-- Node.js installation
-- Plugin dependencies (node_modules)
-- MCP wrapper installation
-- Python 3 (optional, for embeddings)
-- Playwright browser (optional, for web crawling)
-
-Works even when MCP is broken (uses Bash tool directly).
-
-<details>
-<summary><b>❌ Command not found or not recognized</b></summary>
-
-Ensure the plugin is installed and enabled:
-
-```bash
-/plugin list
-/plugin enable bluera-knowledge
-```
-
-If the plugin isn't listed, install it:
-
-```bash
-/plugin marketplace add blueraai/bluera-marketplace
-/plugin install bluera-knowledge@bluera
-```
-</details>
-
-<details>
-<summary><b>🔌 MCP server shows as "failed" in /plugin</b></summary>
-
-If the MCP server shows as failed after installation:
-
-1. **Run `/bluera-knowledge:doctor`** - This diagnoses the most common issues
-2. **Restart Claude Code** - MCP servers require a restart to initialize
-3. **Check logs:** Run `/logs errors` to see recent errors or `/logs module bootstrap` for startup logs
-4. **Check status:** Run `/mcp` to see connection status
-5. **Reinstall:** Try `/plugin uninstall bluera-knowledge` then `/plugin install bluera-knowledge@bluera`
-
-**Common MCP failure causes:**
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `npm ERR! ERESOLVE` in logs | Peer dependency conflict | Fixed in v0.22.6+ with npm flag |
-| Old plugin version running | Multiple cached versions | Fixed in v0.22.7+ (version sorting) |
-| `make not found` | Missing build tools | Install `build-essential` (Linux) |
-| Compilation errors on Node 24 | V8 API changes | Use Node.js v20.x or v22.x |
-
-If the issue persists, check that Claude Code is v2.0.65 or later (earlier versions had MCP loading bugs).
-</details>
-
-<details>
-<summary><b>🌐 Web crawling fails</b></summary>
-
-Check Playwright browser installation:
-
-```bash
-npx playwright install chromium
-```
-
-The plugin attempts to auto-install Playwright browsers on first use, but manual installation may be needed in some environments.
-</details>
-
-<details>
-<summary><b>🔍 Search returns no results</b></summary>
-
-1. Verify store exists: `/bluera-knowledge:stores`
-2. Check store is indexed: `/bluera-knowledge:index <store-name>`
-3. Try broader search terms
-4. Verify you're searching the correct store with `--stores=<name>`
-</details>
-
-<details>
-<summary><b>⚠️ "Model mismatch" error</b></summary>
-
-This error occurs when a store was indexed with a different embedding model than the current configuration. As of v0.20+, stores are indexed with `bge-small-en-v1.5` (previously `all-MiniLM-L6-v2`).
-
-**Solution:** Reindex the affected store:
-
-```bash
-/bluera-knowledge:index <store-name>
-```
-
-**Check model status for all stores:**
-
-```bash
-# Via MCP execute command
-execute stores:check-models
-```
-
-This lists all stores with their embedding model and flags any that need reindexing.
-</details>
-
-<details>
-<summary><b>❓ "Store not found" error</b></summary>
-
-List all stores to see available names and IDs:
-
-```bash
-/bluera-knowledge:stores
-```
-
-Use the exact store name or ID shown in the table.
-</details>
-
-<details>
-<summary><b>🔨 Native module compilation fails (Node.js v24)</b></summary>
-
-tree-sitter and lancedb require native module compilation. Node.js v24 introduced V8 API changes that break these modules.
-
-**Solution:** Use Node.js v20.x or v22.x (LTS versions):
-
-```bash
-# Using nvm
-nvm install 22
-nvm use 22
-```
-
-Run `/bluera-knowledge:doctor` to verify your environment.
-</details>
-
-<details>
-<summary><b>🐧 Linux: "make not found" or build errors</b></summary>
-
-Native modules require build tools:
-
-```bash
-# Debian/Ubuntu
-sudo apt install build-essential
-
-# Fedora/RHEL
-sudo dnf groupinstall "Development Tools"
-```
-
-Then restart Claude Code for auto-setup to complete.
-</details>
-
-<details>
-<summary><b>⏱️ Indexing is slow or fails</b></summary>
-
-Large repositories (10,000+ files) take longer to index. If indexing fails:
-
-1. Check available disk space
-2. Ensure the source repository/folder is accessible
-3. For repo stores, verify git is installed: `git --version`
-4. Check for network connectivity (for repo stores)
-5. Check logs for errors: `/logs errors` or `/logs search "index"`
-</details>
-
-<details>
-<summary><b>🤖 "Claude CLI not found" during crawl</b></summary>
-
-This means intelligent crawling is unavailable. The crawler will automatically use simple BFS mode instead.
-
-To enable intelligent crawling with `--crawl` and `--extract`:
-1. Install Claude Code: https://claude.com/code
-2. Ensure `claude` command is in PATH: `which claude`
-
-Simple mode still crawls effectively—it just doesn't use AI to select which pages to crawl or extract specific content.
-</details>
-
-<details>
-<summary><b>📋 How to view logs for debugging</b></summary>
-
-The plugin logs all MCP server operations to `.bluera/bluera-knowledge/logs/app.log` (relative to project root).
-
-**View logs using the `/logs` command:**
-
-```bash
-/logs              # Watch logs in real-time (tail -f)
-/logs view 50      # View last 50 log entries
-/logs errors       # Show only error-level logs
-/logs module mcp-store  # Filter by module (mcp-server, mcp-store, mcp-execute, mcp-job, mcp-sync, bootstrap)
-/logs search "pattern"  # Search for a pattern
-```
-
-**Log modules:**
-- `bootstrap` - MCP server startup and dependency installation
-- `mcp-server` - Core MCP server operations
-- `mcp-store` - Store create/list/delete operations
-- `mcp-search` - Search queries and results
-- `mcp-execute` - Meta-tool command execution
-- `mcp-job` - Background job status
-- `mcp-sync` - Store sync operations
-
-**Manual access:**
-```bash
-tail -f .bluera/bluera-knowledge/logs/app.log
-```
-
-Logs are JSON formatted (NDJSON) and can be processed with `jq` for pretty-printing.
-</details>
+Run `/bluera-knowledge:doctor` for quick diagnostics (works even when MCP is broken).
+
+**Common issues:** See [docs/troubleshooting.md](docs/troubleshooting.md) for solutions to:
+- Command not found or not recognized
+- MCP server failures
+- Web crawling issues
+- Search returning no results
+- Model mismatch errors
+- Native module compilation (Node.js v24)
+- Linux build tool requirements
+- Slow indexing
+- Log viewing and debugging
 
 ---
 
@@ -827,6 +645,7 @@ This ensures:
 | [Commands Reference](docs/commands.md) | All slash commands with parameters and examples |
 | [Crawler Architecture](docs/crawler-architecture.md) | How the intelligent web crawler works |
 | [Token Efficiency](docs/token-efficiency.md) | How BK reduces token consumption vs web search |
+| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
 | [CONTRIBUTING](CONTRIBUTING.md) | Development setup, testing, and release process |
 
 ---

package/dist/{chunk-S3DJUNUG.js → chunk-BYLIDCWD.js}

@@ -2,7 +2,7 @@ import {
   createLogger,
   summarizePayload,
   truncateForLog
-} from "./chunk-GB5WKUBX.js";
+} from "./chunk-WP2GERAJ.js";
 
 // src/crawl/intelligent-crawler.ts
 import { EventEmitter } from "events";
@@ -916,4 +916,4 @@ export {
   getCrawlStrategy,
   IntelligentCrawler
 };
-//# sourceMappingURL=chunk-S3DJUNUG.js.map
+//# sourceMappingURL=chunk-BYLIDCWD.js.map

package/dist/{chunk-LBE2PTSB.js → chunk-UXT3BCAH.js}

@@ -9,7 +9,7 @@ import {
   isRepoStoreDefinition,
   isWebStoreDefinition,
   summarizePayload
-} from "./chunk-GB5WKUBX.js";
+} from "./chunk-WP2GERAJ.js";
 import {
   checkStoreModelCompatibility
 } from "./chunk-H25AEF47.js";
@@ -2402,4 +2402,4 @@ export {
   createMCPServer,
   runMCPServer
 };
-//# sourceMappingURL=chunk-LBE2PTSB.js.map
+//# sourceMappingURL=chunk-UXT3BCAH.js.map

package/dist/{chunk-GB5WKUBX.js → chunk-WP2GERAJ.js}

@@ -2207,20 +2207,17 @@ var ConfigService = class {
 import { readFile as readFile3, writeFile as writeFile3, access as access2 } from "fs/promises";
 import { join as join6 } from "path";
 var REQUIRED_PATTERNS = [
-  ".bluera/",
-  "!.bluera/",
+  ".bluera/*",
   "!.bluera/bluera-knowledge/",
+  ".bluera/bluera-knowledge/*",
   "!.bluera/bluera-knowledge/stores.config.json",
   "!.bluera/bluera-knowledge/config.json",
   "!.bluera/bluera-knowledge/skill-activation.json",
   ".bluera/bluera-knowledge/data/",
   ".bluera/bluera-knowledge/logs/"
 ];
-var SECTION_HEADER = `
-# Bluera Knowledge
-# Config files (stores.config.json, config.json, skill-activation.json) can be committed
-# Data directory (vector DB, cloned repos) and logs are not committed
-`;
+var SECTION_BEGIN = "# BEGIN Bluera Knowledge";
+var SECTION_END = "# END Bluera Knowledge";
 async function fileExists2(path4) {
   try {
     await access2(path4);
@@ -2229,13 +2226,73 @@ async function fileExists2(path4) {
     return false;
   }
 }
+function isPatternSatisfied(requiredPattern, existingLines) {
+  if (existingLines.includes(requiredPattern)) {
+    return true;
+  }
+  switch (requiredPattern) {
+    case ".bluera/*":
+      return existingLines.includes(".bluera/");
+    case "!.bluera/bluera-knowledge/":
+      return existingLines.includes("!.bluera/bluera-knowledge");
+    case ".bluera/bluera-knowledge/data/":
+    case ".bluera/bluera-knowledge/logs/":
+      return existingLines.includes(".bluera/bluera-knowledge/*");
+    default:
+      return false;
+  }
+}
+function removeBkSection(content) {
+  const lines = content.split("\n");
+  const outputLines = [];
+  let removed = false;
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    const trimmed = line.trim();
+    if (trimmed === SECTION_BEGIN) {
+      removed = true;
+      i++;
+      while (i < lines.length && (lines[i] ?? "").trim() !== SECTION_END) {
+        i++;
+      }
+      if (i < lines.length) {
+        i++;
+      }
+      continue;
+    }
+    if (trimmed === "# Bluera Knowledge") {
+      removed = true;
+      i++;
+      while (i < lines.length) {
+        const lt = (lines[i] ?? "").trim();
+        if (lt === "" || lt.startsWith("#") || lt.includes(".bluera")) {
+          i++;
+        } else {
+          break;
+        }
+      }
+      continue;
+    }
+    outputLines.push(line);
+    i++;
+  }
+  let lastIdx = outputLines.length - 1;
+  while (lastIdx >= 0 && outputLines[lastIdx]?.trim() === "") {
+    outputLines.pop();
+    lastIdx--;
+  }
+  const cleaned = outputLines.length > 0 ? `${outputLines.join("\n")}
+` : "";
+  return { cleaned, removed };
+}
 var GitignoreService = class {
   gitignorePath;
   constructor(projectRoot) {
     this.gitignorePath = join6(projectRoot, ".gitignore");
   }
   /**
-   * Check if all required patterns are present in .gitignore
+   * Check if all required patterns are semantically present in .gitignore
    */
   async hasRequiredPatterns() {
     const exists = await fileExists2(this.gitignorePath);
@@ -2244,50 +2301,62 @@ var GitignoreService = class {
     }
     const content = await readFile3(this.gitignorePath, "utf-8");
     const lines = content.split("\n").map((l) => l.trim());
-    for (const pattern of REQUIRED_PATTERNS) {
-      if (!lines.includes(pattern)) {
-        return false;
-      }
-    }
-    return true;
+    return REQUIRED_PATTERNS.every((pattern) => isPatternSatisfied(pattern, lines));
   }
   /**
    * Ensure required .gitignore patterns are present.
    *
    * - Creates .gitignore if it doesn't exist
-   * - Appends missing patterns if .gitignore exists
-   * - Does nothing if all patterns are already present
+   * - Removes existing managed sections (old or new format)
+   * - Appends only semantically missing patterns with BEGIN/END markers
+   * - Persists cleanup even when no patterns are missing
    *
    * @returns Object with updated flag and descriptive message
    */
   async ensureGitignorePatterns() {
     const exists = await fileExists2(this.gitignorePath);
     if (!exists) {
-      const content = `${SECTION_HEADER.trim()}
-${REQUIRED_PATTERNS.join("\n")}
-`;
+      const content = [SECTION_BEGIN, ...REQUIRED_PATTERNS, SECTION_END, ""].join("\n");
       await writeFile3(this.gitignorePath, content);
       return {
         updated: true,
         message: "Created .gitignore with Bluera Knowledge patterns"
       };
     }
-    const existingContent = await readFile3(this.gitignorePath, "utf-8");
-    const lines = existingContent.split("\n").map((l) => l.trim());
-    const missingPatterns = REQUIRED_PATTERNS.filter((pattern) => !lines.includes(pattern));
+    let rawContent = await readFile3(this.gitignorePath, "utf-8");
+    rawContent = rawContent.replace(/\r\n/g, "\n");
+    const { cleaned, removed } = removeBkSection(rawContent);
+    const cleanedLines = cleaned.split("\n").map((l) => l.trim());
+    const missingPatterns = REQUIRED_PATTERNS.filter(
+      (pattern) => !isPatternSatisfied(pattern, cleanedLines)
+    );
     if (missingPatterns.length === 0) {
+      if (removed) {
+        await writeFile3(this.gitignorePath, cleaned);
+        return {
+          updated: true,
+          message: "Cleaned redundant Bluera Knowledge section from .gitignore"
+        };
+      }
       return {
         updated: false,
         message: "All Bluera Knowledge patterns already present in .gitignore"
       };
     }
-    let newContent = existingContent;
-    if (!newContent.endsWith("\n")) {
+    let newContent = cleaned;
+    if (newContent.length > 0) {
+      if (!newContent.endsWith("\n")) {
+        newContent += "\n";
+      }
       newContent += "\n";
     }
-    newContent += SECTION_HEADER;
-    newContent += `${missingPatterns.join("\n")}
-`;
+    newContent += [SECTION_BEGIN, ...missingPatterns, SECTION_END, ""].join("\n");
+    if (newContent === rawContent) {
+      return {
+        updated: false,
+        message: "All Bluera Knowledge patterns already present in .gitignore"
+      };
+    }
     await writeFile3(this.gitignorePath, newContent);
     return {
       updated: true,
@@ -6625,4 +6694,4 @@ export {
   createServices,
   destroyServices
 };
-//# sourceMappingURL=chunk-GB5WKUBX.js.map
+//# sourceMappingURL=chunk-WP2GERAJ.js.map