bluera-knowledge 0.22.4 → 0.22.6

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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.22.6](https://github.com/blueraai/bluera-knowledge/compare/v0.22.4...v0.22.6) (2026-02-01)
+
+
+### Bug Fixes
+
+* **deps:** make tree-sitter optional for Node.js v24 compatibility ([acd6618](https://github.com/blueraai/bluera-knowledge/commit/acd66185813b4841a4c0abdd2edce10db9e08fef))
+* **setup:** add --legacy-peer-deps to resolve tree-sitter peer conflict ([9b0b101](https://github.com/blueraai/bluera-knowledge/commit/9b0b1014e9ec0cec90c63a6a4cfdd81533248b2b))
+
+## [0.22.5](https://github.com/blueraai/bluera-knowledge/compare/v0.22.4...v0.22.5) (2026-02-01)
+
+
+### Bug Fixes
+
+* **deps:** make tree-sitter optional for Node.js v24 compatibility ([acd6618](https://github.com/blueraai/bluera-knowledge/commit/acd66185813b4841a4c0abdd2edce10db9e08fef))
+
 ## [0.22.4](https://github.com/blueraai/bluera-knowledge/compare/v0.21.6...v0.22.4) (2026-02-01)
 
 

package/README.md

@@ -4,7 +4,7 @@
 ![NPM Version](https://img.shields.io/npm/v/bluera-knowledge)
 ![NPM Downloads](https://img.shields.io/npm/dm/bluera-knowledge)
 ![License](https://img.shields.io/badge/license-MIT-green)
-![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
+![Node](https://img.shields.io/badge/node-20.x%20%7C%2022.x-brightgreen)
 ![Python](https://img.shields.io/badge/python-optional-lightgrey)
 
 > 🚀 **Build a local knowledge base for your AI coding agent—dependency source code, crawled docs, and your own files, all instantly searchable.**
@@ -84,6 +84,14 @@ Adds slash commands, MCP tools, and Skills for optimal Claude Code integration.
 > [!NOTE]
 > Setup runs automatically on first session start (installs dependencies and Playwright browser). If you see "Setup running in background...", wait ~30s and restart Claude Code.
 
+### Prerequisites
+
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Node.js | v20.x or v22.x | LTS recommended. v24+ not yet supported (native module compatibility) |
+| Build tools | - | `make` + C++ compiler (`build-essential` on Debian/Ubuntu, Xcode CLI on macOS) |
+| Python 3 | Optional | Enables code-graph features |
+
 ---
 
 ## ✨ Why Bluera Knowledge?
@@ -444,6 +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>
 
@@ -529,6 +549,38 @@ List all stores to see available names and IDs:
 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>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.22.4",
+  "version": "0.22.6",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {
@@ -56,7 +56,7 @@
   "author": "Bluera",
   "license": "MIT",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.0.0 <24.0.0"
   },
   "repository": {
     "type": "git",
@@ -118,11 +118,13 @@
     "pino-roll": "^4.0.0",
     "playwright": "^1.58.0",
     "slurp-ai": "^1.0.6",
-    "tree-sitter": "^0.25.0",
-    "tree-sitter-go": "^0.25.0",
-    "tree-sitter-rust": "^0.24.0",
     "turndown": "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2",
     "zod": "^4.3.5"
+  },
+  "optionalDependencies": {
+    "tree-sitter": "^0.25.0",
+    "tree-sitter-go": "^0.25.0",
+    "tree-sitter-rust": "^0.24.0"
   }
 }