bluera-knowledge 0.13.1 → 0.13.3

package/dist/{chunk-GCUKVV33.js → chunk-AOSDVRRH.js}

@@ -3,7 +3,7 @@ import {
   createLogger,
   summarizePayload,
   truncateForLog
-} from "./chunk-6ZVW2P2F.js";
+} from "./chunk-AJI5DCKY.js";
 
 // src/crawl/intelligent-crawler.ts
 import { EventEmitter } from "events";
@@ -753,4 +753,4 @@ var IntelligentCrawler = class extends EventEmitter {
 export {
   IntelligentCrawler
 };
-//# sourceMappingURL=chunk-GCUKVV33.js.map
+//# sourceMappingURL=chunk-AOSDVRRH.js.map

package/dist/{chunk-H5AKKHY7.js → chunk-XL2UHMBL.js}

@@ -7,7 +7,7 @@ import {
   createStoreId,
   destroyServices,
   summarizePayload
-} from "./chunk-6ZVW2P2F.js";
+} from "./chunk-AJI5DCKY.js";
 
 // src/mcp/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -2151,4 +2151,4 @@ export {
   createMCPServer,
   runMCPServer
 };
-//# sourceMappingURL=chunk-H5AKKHY7.js.map
+//# sourceMappingURL=chunk-XL2UHMBL.js.map

package/dist/index.js

@@ -7,10 +7,10 @@ import {
   isWebStoreDefinition,
   runMCPServer,
   spawnBackgroundWorker
-} from "./chunk-H5AKKHY7.js";
+} from "./chunk-XL2UHMBL.js";
 import {
   IntelligentCrawler
-} from "./chunk-GCUKVV33.js";
+} from "./chunk-AOSDVRRH.js";
 import {
   ASTParser,
   AdapterRegistry,
@@ -24,7 +24,7 @@ import {
   err,
   extractRepoName,
   ok
-} from "./chunk-6ZVW2P2F.js";
+} from "./chunk-AJI5DCKY.js";
 import "./chunk-HRQD3MPH.js";
 
 // src/index.ts

package/dist/mcp/server.js

@@ -1,8 +1,8 @@
 import {
   createMCPServer,
   runMCPServer
-} from "../chunk-H5AKKHY7.js";
-import "../chunk-6ZVW2P2F.js";
+} from "../chunk-XL2UHMBL.js";
+import "../chunk-AJI5DCKY.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-GCUKVV33.js";
+} from "../chunk-AOSDVRRH.js";
 import {
   JobService,
   createDocumentId,
@@ -10,7 +10,7 @@ import {
   createStoreId,
   destroyServices,
   shutdownLogger
-} from "../chunk-6ZVW2P2F.js";
+} from "../chunk-AJI5DCKY.js";
 import "../chunk-HRQD3MPH.js";
 
 // src/workers/background-worker-cli.ts

package/docs/cli.md

@@ -0,0 +1,170 @@
+# CLI Reference
+
+Complete reference for the Bluera Knowledge CLI tool (npm package).
+
+> **Note:** When using CLI without Claude Code installed, web crawling uses simple BFS mode. Install Claude Code to unlock `--crawl` (AI-guided URL selection) and `--extract` (AI content extraction) instructions.
+
+## Installation
+
+```bash
+# Global install (CLI available everywhere)
+npm install -g bluera-knowledge
+
+# Or project install
+npm install --save-dev bluera-knowledge
+```
+
+---
+
+## Store Management
+
+### Create a Store
+
+```bash
+# Add a Git repository
+bluera-knowledge store create react --type repo --source https://github.com/facebook/react
+
+# Add a Git repository with specific branch
+bluera-knowledge store create react-canary --type repo --source https://github.com/facebook/react --branch canary
+
+# Add a local folder
+bluera-knowledge store create my-docs --type file --source ./docs
+
+# Add a web crawl
+bluera-knowledge store create fastapi-docs --type web --source https://fastapi.tiangolo.com
+```
+
+**Create Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-t, --type <type>` | Store type: `file`, `repo`, or `web` (required) |
+| `-s, --source <path>` | Local path or URL (required) |
+| `-b, --branch <branch>` | Git branch to clone (repo stores only) |
+| `-d, --description <desc>` | Optional store description |
+| `--tags <tags>` | Comma-separated tags for filtering |
+
+### List Stores
+
+```bash
+bluera-knowledge store list
+bluera-knowledge store list --type repo  # Filter by type
+```
+
+### Store Info
+
+```bash
+bluera-knowledge store info react
+```
+
+### Delete a Store
+
+```bash
+# Interactive deletion (prompts for confirmation in TTY mode)
+bluera-knowledge store delete old-store
+
+# Force delete without confirmation
+bluera-knowledge store delete old-store --force
+bluera-knowledge store delete old-store -y
+```
+
+**Delete Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-f, --force` | Delete without confirmation prompt |
+| `-y, --yes` | Alias for `--force` |
+
+---
+
+## Indexing
+
+### Index a Store
+
+```bash
+# Re-index a store (only changed files)
+bluera-knowledge index react
+
+# Force re-index all files (ignores cache)
+bluera-knowledge index react --force
+
+# Watch for changes and auto-reindex
+bluera-knowledge index watch react
+bluera-knowledge index watch react --debounce 2000  # Custom debounce (default: 1000ms)
+```
+
+**Index Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-f, --force` | Re-index all files (ignore incremental cache) |
+
+**Watch Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--debounce <ms>` | Debounce delay for file changes (default: 1000ms) |
+
+---
+
+## Searching
+
+```bash
+# Search across all stores
+bluera-knowledge search "how does useEffect work"
+
+# Search specific stores
+bluera-knowledge search "routing" --stores react,vue
+
+# Get more results with full content
+bluera-knowledge search "middleware" --limit 20 --include-content
+
+# Filter irrelevant results (returns empty if nothing is truly relevant)
+bluera-knowledge search "kubernetes deployment" --min-relevance 0.4
+
+# Get JSON output with confidence and raw scores
+bluera-knowledge search "express middleware" --format json
+```
+
+**Search Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-s, --stores <stores>` | Comma-separated store names/IDs |
+| `-m, --mode <mode>` | `hybrid` (default), `vector`, or `fts` |
+| `-n, --limit <count>` | Max results (default: 10) |
+| `-t, --threshold <score>` | Min normalized score (0-1) |
+| `--min-relevance <score>` | Min raw cosine similarity (0-1) |
+| `--include-content` | Show full content in results |
+| `--detail <level>` | `minimal`, `contextual`, or `full` |
+
+---
+
+## Global Options
+
+```bash
+--config <path>        # Custom config file
+--data-dir <path>      # Custom data directory
+--project-root <path>  # Project root for store definitions (required for sync)
+--format <format>      # Output format: json | table | plain
+--quiet                # Suppress non-essential output
+--verbose              # Enable verbose logging
+```
+
+---
+
+## When to Use CLI vs Plugin
+
+**Use CLI when:**
+- Using an editor other than Claude Code (VSCode, Cursor, etc.)
+- Integrating into CI/CD pipelines
+- Scripting or automation
+- Pre-indexing dependencies for teams
+
+**Use Plugin when:**
+- Working within Claude Code
+- Want slash commands (`/bluera-knowledge:search`)
+- Need Claude to automatically query your knowledge base
+- Want Skills to guide optimal usage
+
+Both interfaces use the same underlying services, so you can switch between them seamlessly.

package/docs/commands.md

@@ -0,0 +1,392 @@
+# Commands Reference
+
+Complete reference for all Bluera Knowledge slash commands.
+
+## Quick Reference
+
+| Command | Purpose | Arguments |
+|---------|---------|-----------|
+| `/bluera-knowledge:suggest` | Analyze project dependencies | None |
+| `/bluera-knowledge:add-repo` | Clone and index Git repository | `<url> [--name=<name>] [--branch=<branch>]` |
+| `/bluera-knowledge:add-folder` | Index local folder | `<path> --name=<name>` |
+| `/bluera-knowledge:search` | Search knowledge stores | `"<query>" [--stores=<names>] [--limit=<N>]` |
+| `/bluera-knowledge:stores` | List all stores | None |
+| `/bluera-knowledge:index` | Re-index a store | `<store-name-or-id>` |
+| `/bluera-knowledge:remove-store` | Delete a store and all data | `<store-name-or-id>` |
+| `/bluera-knowledge:crawl` | Crawl web pages | `<url> <store-name> [--crawl "<instruction>"]` |
+| `/bluera-knowledge:sync` | Sync stores from definitions config | `[--dry-run] [--prune]` |
+
+---
+
+## `/bluera-knowledge:suggest`
+
+**Analyze your project to suggest libraries worth indexing as knowledge stores**
+
+```bash
+/bluera-knowledge:suggest
+```
+
+Scans source files, counts import statements, and suggests the top 5 most-used dependencies with their repository URLs.
+
+**Supported languages:**
+
+| Language | Manifest File | Registry |
+|----------|---------------|----------|
+| JavaScript/TypeScript | `package.json` | NPM |
+| Python | `requirements.txt`, `pyproject.toml` | PyPI |
+| Rust | `Cargo.toml` | crates.io |
+| Go | `go.mod` | Go modules |
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+## Dependency Analysis
+
+Scanned 342 source files and found 24 dependencies.
+
+### Top Dependencies by Usage
+
+1. **react** (156 imports across 87 files)
+   Repository: https://github.com/facebook/react
+
+   Add with:
+   /bluera-knowledge:add-repo https://github.com/facebook/react --name=react
+
+2. **vitest** (40 imports across 40 files)
+   Repository: https://github.com/vitest-dev/vitest
+
+   Add with:
+   /bluera-knowledge:add-repo https://github.com/vitest-dev/vitest --name=vitest
+
+3. **lodash** (28 imports across 15 files)
+   Repository: https://github.com/lodash/lodash
+
+   Add with:
+   /bluera-knowledge:add-repo https://github.com/lodash/lodash --name=lodash
+
+---
+
+Already indexed: typescript, express
+```
+</details>
+
+---
+
+## `/bluera-knowledge:add-repo`
+
+**Clone and index a Git repository**
+
+```bash
+/bluera-knowledge:add-repo <url> [--name=<name>] [--branch=<branch>]
+```
+
+**Examples:**
+```bash
+/bluera-knowledge:add-repo https://github.com/lodash/lodash
+/bluera-knowledge:add-repo https://github.com/facebook/react --branch=main --name=react
+```
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+✓ Cloning https://github.com/facebook/react...
+✓ Created store: react (a1b2c3d4...)
+  Location: ~/.local/share/bluera-knowledge/stores/a1b2c3d4.../
+
+✓ Indexing...
+✓ Indexed 1,247 files
+
+Store is ready for searching!
+```
+</details>
+
+---
+
+## `/bluera-knowledge:add-folder`
+
+**Index a local folder**
+
+```bash
+/bluera-knowledge:add-folder <path> --name=<name>
+```
+
+**Use cases:**
+- Project documentation
+- Coding standards
+- Design documents
+- API specifications
+- Reference materials
+- Any other content
+
+**Examples:**
+```bash
+/bluera-knowledge:add-folder ./docs --name=project-docs
+/bluera-knowledge:add-folder ./architecture --name=design-docs
+```
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+✓ Adding folder: ~/my-project/docs...
+✓ Created store: project-docs (e5f6g7h8...)
+  Location: ~/.local/share/bluera-knowledge/stores/e5f6g7h8.../
+
+✓ Indexing...
+✓ Indexed 342 files
+
+Store is ready for searching!
+```
+</details>
+
+---
+
+## `/bluera-knowledge:search`
+
+**Search across indexed knowledge stores**
+
+```bash
+/bluera-knowledge:search "<query>" [--stores=<names>] [--limit=<number>] [--min-relevance=<0-1>]
+```
+
+**Options:**
+- `--stores=<names>` - Comma-separated store names to search (default: all stores)
+- `--limit=<number>` - Maximum results to return (default: 10)
+- `--min-relevance=<0-1>` - Minimum raw cosine similarity; returns empty if no results meet threshold
+- `--threshold=<0-1>` - Minimum normalized score to include results
+- `--mode=<mode>` - Search mode: `hybrid` (default), `vector`, or `fts`
+- `--detail=<level>` - Context detail: `minimal` (default), `contextual`, or `full`
+
+**Examples:**
+```bash
+# Search all stores
+/bluera-knowledge:search "how to invalidate queries"
+
+# Search specific store
+/bluera-knowledge:search "useState implementation" --stores=react
+
+# Search multiple stores (comma-separated)
+/bluera-knowledge:search "deep clone" --stores=react,lodash
+
+# Limit results
+/bluera-knowledge:search "testing patterns" --limit=5
+
+# Filter irrelevant results (returns empty if nothing is truly relevant)
+/bluera-knowledge:search "kubernetes deployment" --min-relevance=0.4
+```
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+## Search Results: "button component" (hybrid search)
+
+**1. [Score: 0.95] [Vector+FTS]**
+Store: react
+File: src/components/Button.tsx
+Purpose: → Reusable button component with variants
+Top Terms: (in this chunk): button, variant, size, color, onClick
+Imports: (in this chunk): React, clsx
+
+**2. [Score: 0.87] [Vector]**
+Store: react
+File: src/hooks/useButton.ts
+Purpose: → Custom hook for button state management
+Top Terms: (in this chunk): hook, state, pressed, disabled
+Imports: (in this chunk): useState, useCallback
+
+**3. [Score: 0.81] [Vector+FTS]**
+Store: react
+File: src/components/IconButton.tsx
+Purpose: → Button component with icon support
+Top Terms: (in this chunk): icon, button, aria-label, accessible
+
+---
+**Found 3 results in 45ms**
+
+**Next Steps:**
+- Read file: `Read src/components/Button.tsx`
+- Get full code: `mcp__bluera-knowledge__get_full_context("result-id")`
+- Refine search: Use keywords above
+```
+</details>
+
+---
+
+## `/bluera-knowledge:stores`
+
+**List all indexed knowledge stores**
+
+```bash
+/bluera-knowledge:stores
+```
+
+Shows store name, type, ID, and source location in a clean table format.
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+| Name | Type | ID | Source |
+|------|------|----|--------------------|
+| react | repo | 459747c7 | https://github.com/facebook/react |
+| crawl4ai | repo | b5a72a94 | https://github.com/unclecode/crawl4ai.git |
+| project-docs | file | 70f6309b | ~/repos/my-project/docs |
+| claude-docs | web | 9cc62018 | https://code.claude.com/docs |
+
+**Total**: 4 stores
+```
+</details>
+
+---
+
+## `/bluera-knowledge:index`
+
+**Re-index an existing store to update the search index**
+
+```bash
+/bluera-knowledge:index <store-name-or-id>
+```
+
+**When to re-index:**
+- The source repository has been updated (for repo stores)
+- Files have been added or modified (for file stores)
+- Search results seem out of date
+
+**Example:**
+```bash
+/bluera-knowledge:index react
+```
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+✓ Indexing store: react...
+✓ Indexed 1,247 documents in 3,421ms
+
+Store search index is up to date!
+```
+</details>
+
+---
+
+## `/bluera-knowledge:remove-store`
+
+**Delete a knowledge store and all associated data**
+
+```bash
+/bluera-knowledge:remove-store <store-name-or-id>
+```
+
+**What gets deleted:**
+- Store registry entry
+- LanceDB search index (vector embeddings)
+- Cloned repository files (for repo stores created from URLs)
+
+**Example:**
+```bash
+/bluera-knowledge:remove-store react
+```
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+Store "react" deleted successfully.
+
+Removed:
+- Store registry entry
+- LanceDB search index
+- Cloned repository files
+```
+</details>
+
+---
+
+## `/bluera-knowledge:crawl`
+
+**Crawl web pages with natural language control**
+
+```bash
+/bluera-knowledge:crawl <url> <store-name> [options]
+```
+
+**Options:**
+- `--crawl "<instruction>"` - Natural language instruction for which pages to crawl
+- `--extract "<instruction>"` - Natural language instruction for what content to extract
+- `--simple` - Use simple BFS mode instead of intelligent crawling
+- `--max-pages <n>` - Maximum pages to crawl (default: 50)
+- `--fast` - Use fast axios-only mode (may fail on JavaScript-heavy sites)
+
+**Requirements:**
+- Python 3 with `crawl4ai` package installed
+- Web store is auto-created if it doesn't exist
+
+**Examples:**
+```bash
+# Basic crawl
+/bluera-knowledge:crawl https://docs.example.com/guide my-docs
+
+# Intelligent crawl with custom strategy
+/bluera-knowledge:crawl https://react.dev react-docs --crawl "all API reference pages"
+
+# Extract specific content from pages
+/bluera-knowledge:crawl https://example.com/pricing pricing --extract "pricing tiers and features"
+
+# Combine crawl strategy + extraction
+/bluera-knowledge:crawl https://docs.python.org python-docs \
+  --crawl "standard library modules" \
+  --extract "function signatures and examples"
+
+# JavaScript-rendered sites work by default (uses headless browser)
+/bluera-knowledge:crawl https://nextjs.org/docs nextjs-docs --max-pages 30
+
+# Fast mode for static HTML sites (axios-only, faster but may miss JS content)
+/bluera-knowledge:crawl https://example.com/static static-docs --fast --max-pages 100
+
+# Simple BFS mode (no AI guidance)
+/bluera-knowledge:crawl https://example.com/docs docs --simple --max-pages 100
+```
+
+The crawler converts pages to markdown and indexes them for semantic search.
+
+---
+
+## `/bluera-knowledge:sync`
+
+**Sync stores from definitions config (bootstrap on fresh clone)**
+
+```bash
+/bluera-knowledge:sync [options]
+```
+
+**Options:**
+- `--dry-run` - Show what would happen without making changes
+- `--prune` - Remove stores not in definitions
+- `--reindex` - Re-index existing stores after sync
+
+**Use cases:**
+- **Fresh clone**: Recreate all stores defined by the team
+- **Check status**: See which stores exist vs. defined
+- **Clean up**: Remove orphan stores not in config
+
+**Examples:**
+```bash
+# Preview what would be synced
+/bluera-knowledge:sync --dry-run
+
+# Sync all stores from definitions
+/bluera-knowledge:sync
+
+# Sync and remove orphan stores
+/bluera-knowledge:sync --prune
+```
+
+**How it works:**
+1. Reads store definitions from `.bluera/bluera-knowledge/stores.config.json`
+2. Creates any stores that don't exist locally
+3. Reports orphan stores (local stores not in definitions)
+4. Optionally prunes orphans with `--prune`