bluera-knowledge 0.13.0 → 0.13.1

package/.claude/rules/code-quality.md

@@ -0,0 +1,12 @@
+# Code Quality Rules
+
+## Fail Early and Fast
+
+Our code is expected to *work* as-designed:
+- Use `throw` when state is unexpected or for any error condition
+- Use 100% strict typing; no `any` no `as`, unless completely unavoidable and considered best practice
+
+## Never
+
+- Write "fallback code" or "graceful degradation" code or implement "defaults" *unless* it's part of the specification
+- Leave commented code, nor reference outdated/deprecated implementations

package/.claude/rules/git.md

@@ -0,0 +1,5 @@
+# Git Rules
+
+## Never
+
+- Use `--no-verify` on Git commits; this anti-pattern completely circumvents the code protections we have in place

package/.claude/rules/versioning.md

@@ -0,0 +1,7 @@
+# Versioning Rules
+
+## Always
+
+- Use the `bun run version:*` commands after changes
+  - Without this, the changes would not be detected by Claude Code
+- Push to main after version bump - releases happen automatically (no manual tagging needed)

package/CLAUDE.md

@@ -101,18 +101,10 @@ Note: Version scripts run full quality checks BEFORE bumping to prevent broken r
 1. Run `bun run build` (or `bun run precommit` which includes build)
 2. Commit both source AND dist/ changes together
 
-## ALWAYS
+## Project Rules
 
-* use the `bun run version:*` commands after changes
-    * without this, the changes would not be detected by Claude Code
-* push to main after version bump - releases happen automatically (no manual tagging needed)
-* fail early and fast
-  * our code is expected to *work* as-designed
-    * use "throw" when state is unexpected or for any error condition
-    * use 100% strict typing; no "any" no "as", unless completely unavoidable and considerd best practice
+Modular rules are in `.claude/rules/` and auto-load:
 
-## NEVER
-
-* use `--no-verify` on Git commits; this anti-pattern completely circumvents the code protections we have in place
-* write "fallback code" or "graceful degradation" code or implement "defaults" *unless* it's part of the specification
-* leave commented code, nor reference outdated/deprecated implementations
+- `code-quality.md` - Fail early/fast, strict typing, no fallback code
+- `git.md` - No --no-verify on commits
+- `versioning.md` - Use version:* commands, push to main for releases

package/README.md

@@ -1180,6 +1180,14 @@ pip install crawl4ai
 playwright install chromium
 ```
 
+**Disable auto-install (security-conscious environments):**
+
+Set the `BK_SKIP_AUTO_INSTALL` environment variable to disable automatic pip package installation:
+
+```bash
+export BK_SKIP_AUTO_INSTALL=1
+```
+
 > [!NOTE]
 > The plugin will work without crawl4ai/playwright, but web crawling features (`/bluera-knowledge:crawl`) will be unavailable. The default mode uses headless browser for maximum compatibility with JavaScript-rendered sites. Use `--fast` for static sites when speed is critical.
 

package/commands/crawl.md

@@ -1,7 +1,8 @@
 ---
 description: Crawl web pages with natural language control and add to knowledge store
 argument-hint: "[url] [store-name] [--crawl instruction] [--extract instruction] [--fast]"
-allowed-tools: [Bash(*)]
+allowed-tools: ["Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/index.js crawl:*)"]
+context: fork
 ---
 
 Crawling and indexing: $ARGUMENTS

package/commands/test-plugin.md

@@ -1,24 +1,58 @@
+---
+description: Run comprehensive plugin validation test suite
+argument-hint: "[--dev]"
+context: fork
+---
+
 # Test Plugin
 
-Comprehensive test of all Bluera Knowledge plugin functionality (MCP tools + slash commands).
+Comprehensive test of all Bluera Knowledge plugin functionality.
+
+## When to Use Each Mode
+
+| Scenario | Command | Tests |
+|----------|---------|-------|
+| Claude running with `--plugin-dir .` | `/test-plugin` | 19/19 (full suite) |
+| Plugin installed from marketplace | `/test-plugin` | 19/19 (full suite) |
+| Claude running WITHOUT plugin loaded | `/test-plugin --dev` | 16/19 (no slash cmds) |
+| CI/CD or scripted testing (no Claude) | `--dev` via bash | 16/19 (no slash cmds) |
+
+**Modes:**
+- **Default mode**: Uses Claude's MCP tools. Works when plugin is loaded via `--plugin-dir .` or installed from marketplace. Runs all 19 tests including slash commands.
+- **`--dev` mode**: Spawns MCP server directly via `scripts/test-mcp-dev.js`. Works without Claude Code or when plugin isn't loaded. Skips slash command tests (8-10) since they require Claude's skill router.
+
+**Recommendation:** If developing with `claude --plugin-dir .`, use default mode (no `--dev` flag) for full test coverage.
 
 ## Context
 
 !`echo "=== BK Plugin Test ===" && ls -la .bluera/bluera-knowledge/ 2>/dev/null || echo "No BK data dir yet (will be created)"`
 
+## Mode Detection
+
+Check if `--dev` flag is present in: $ARGUMENTS
+
+- If `--dev` is present: Use **Development Mode** (MCP via scripts/test-mcp-dev.js)
+- Otherwise: Use **Production Mode** (MCP via Claude's built-in tools)
+
+---
+
 ## Pre-Test Cleanup
 
 First, clean up any leftover artifacts from previous test runs (ignore errors if they don't exist):
 
-1. Delete test store if exists: Call MCP tool `execute` with `{ command: "store:delete", args: { store: "bk-test-store" } }` - ignore "not found" errors
-2. Remove test content directory:
-   ```bash
-   rm -rf .bluera/bluera-knowledge/test-content
-   ```
+**In `--dev` mode:**
+```bash
+node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-store"}}' 2>/dev/null || true
+rm -rf .bluera/bluera-knowledge/test-content
+```
+
+**In production mode:**
+1. Call MCP tool `execute` with `{ command: "store:delete", args: { store: "bk-test-store" } }` - ignore errors
+2. Run: `rm -rf .bluera/bluera-knowledge/test-content`
 
 ## Test Content Setup
 
-First, create test content for indexing:
+Create test content for indexing:
 
 ```bash
 mkdir -p .bluera/bluera-knowledge/test-content
@@ -40,136 +74,225 @@ EOF
 
 Execute each test in order. Mark each as PASS or FAIL.
 
+---
+
+# DEVELOPMENT MODE (`--dev`)
+
+Use this section if `--dev` flag is present. Uses `scripts/test-mcp-dev.js` to spawn MCP server directly.
+
+### Part 1: MCP Server Tests (via dev script)
+
+1. **MCP Connection**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"help"}'
+   ```
+   - PASS if output contains "Available commands"
+
+2. **List Stores**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"stores"}'
+   ```
+   - PASS if no error (may return empty array)
+
+3. **Create Store**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"store:create","args":{"name":"bk-test-store","type":"file","source":".bluera/bluera-knowledge/test-content"}}'
+   ```
+   - PASS if response indicates success
+
+4. **Store Info**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"store:info","args":{"store":"bk-test-store"}}'
+   ```
+   - PASS if response contains store details
+
+5. **Index Store** (via CLI for reliability):
+   ```bash
+   node dist/index.js index bk-test-store
+   ```
+   - PASS if output shows "Indexed X documents"
+
+6-7. **Search + Get Full Context** (session mode to maintain cache):
+   ```bash
+   node scripts/test-mcp-dev.js session << 'EOF'
+search {"query":"validateBKPlugin","stores":["bk-test-store"]}
+get_full_context {"resultId":"$LAST_ID"}
+EOF
+   ```
+   - PASS if first result has non-empty results array
+   - PASS if second result contains "BK Plugin Test File"
+
+### Part 2: Slash Commands (SKIPPED in --dev mode)
+
+Tests 8-10 are skipped in development mode because slash commands require Claude Code to invoke them. The MCP server tests (Part 1) provide equivalent coverage of the underlying functionality.
+
+### Part 3: Hook Tests (same for both modes)
+
+[Continue to Part 3 below]
+
+### Part 4: Cleanup (--dev mode)
+
+17. **Delete Store**:
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-store"}}'
+    ```
+    - PASS if deletion succeeds
+
+18. **Remove Test Content**:
+    ```bash
+    rm -rf .bluera/bluera-knowledge/test-content
+    ```
+    - PASS if command succeeds
+
+19. **Verify Cleanup**:
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"stores"}'
+    ```
+    - PASS if bk-test-store is NOT in the list
+
+---
+
+# PRODUCTION MODE (default)
+
+Use this section if `--dev` flag is NOT present. Uses Claude's built-in MCP tools.
+
 ### Part 1: MCP Tools
 
 1. **MCP Connection**: Call MCP tool `execute` with `{ command: "help" }`
-   - Expected: Returns list of available commands
    - PASS if response contains "Available commands"
 
 2. **List Stores (MCP)**: Call MCP tool `execute` with `{ command: "stores" }`
-   - Expected: Returns store list (may be empty initially)
    - PASS if no error
 
 3. **Create Store**: Call MCP tool `execute` with:
    ```json
    { "command": "store:create", "args": { "name": "bk-test-store", "type": "file", "source": ".bluera/bluera-knowledge/test-content" } }
    ```
-   - Expected: Store created successfully
    - PASS if response indicates success
 
 4. **Store Info**: Call MCP tool `execute` with:
    ```json
    { "command": "store:info", "args": { "store": "bk-test-store" } }
    ```
-   - Expected: Returns store metadata including name, type, path
    - PASS if response contains store details
 
-5. **Index Store**: Run CLI command via Bash (MCP's store:index spawns background jobs that don't complete reliably):
+5. **Index Store**: Run CLI command via Bash:
    ```bash
    node dist/index.js index bk-test-store
    ```
-   - Expected: Output shows "Indexed X documents, Y chunks"
    - PASS if indexing completes successfully
 
 6. **Search (MCP)**: Call MCP tool `search` with:
    ```json
    { "query": "validateBKPlugin", "stores": ["bk-test-store"] }
    ```
-   - Expected: Returns results containing test content
-   - PASS if results array is non-empty and contains test file
+   - PASS if results array is non-empty
 
-7. **Get Full Context**: If search returned results, call MCP tool `get_full_context` with:
-   ```json
-   { "resultId": "<id from search result>" }
-   ```
-   - Expected: Returns full file content
+7. **Get Full Context**: Call MCP tool `get_full_context` with resultId from step 6
    - PASS if response contains "BK Plugin Test File"
 
 ### Part 2: Slash Commands
 
 8. **Stores Command**: Run `/bluera-knowledge:stores`
-   - Expected: Shows bk-test-store in output
-   - PASS if store is listed
+   - PASS if bk-test-store is listed
 
 9. **Search Command**: Run `/bluera-knowledge:search "bluera-knowledge-test"`
-   - Expected: Returns results from test store
    - PASS if results are shown
 
 10. **Suggest Command**: Run `/bluera-knowledge:suggest`
-    - Expected: Runs without error (may show no suggestions if no package.json)
     - PASS if no error thrown
 
-### Part 3: Hook Tests
+### Part 3: Hook Tests (same for both modes)
+
+[Continue to Part 3 below]
 
-These tests verify that plugin hooks work correctly by running hook scripts directly with simulated input.
+### Part 4: Cleanup (production mode)
 
-11. **Hook Registration**: Verify hooks.json has expected structure
+17. **Delete Store**: Call MCP tool `execute` with:
+    ```json
+    { "command": "store:delete", "args": { "store": "bk-test-store" } }
+    ```
+    - PASS if deletion succeeds
+
+18. **Remove Test Content**:
     ```bash
-    cat .claude-plugin/hooks/hooks.json 2>/dev/null || cat hooks/hooks.json | jq -e '.hooks.PostToolUse and .hooks.UserPromptSubmit and .hooks.SessionStart'
+    rm -rf .bluera/bluera-knowledge/test-content
     ```
-    - Expected: Returns `true` (all hook types registered)
-    - PASS if command succeeds with truthy output
+    - PASS if command succeeds
 
-12. **PostToolUse Hook - Library Detection**: Run hook with simulated node_modules read
+19. **Verify Cleanup**: Call MCP tool `execute` with `{ command: "stores" }`
+    - PASS if bk-test-store is NOT in the list
+
+---
+
+# Part 3: Hook Tests (both modes)
+
+These tests verify that plugin hooks work correctly by running hook scripts directly.
+
+11. **Hook Registration**:
+    ```bash
+    cat hooks/hooks.json | jq -e '.hooks.PostToolUse and .hooks.UserPromptSubmit and .hooks.SessionStart'
+    ```
+    - PASS if returns `true`
+
+12. **PostToolUse Hook - Library Detection**:
     ```bash
     echo '{"tool_name": "Read", "tool_input": {"file_path": "/project/node_modules/express/index.js"}}' | python3 hooks/posttooluse-bk-reminder.py
     ```
-    - Expected: JSON output with `hookSpecificOutput.additionalContext` containing "BLUERA-KNOWLEDGE REMINDER"
-    - PASS if output contains reminder text and library name "express"
+    - PASS if output contains "BLUERA-KNOWLEDGE REMINDER" and "express"
 
-13. **PostToolUse Hook - Non-Library (Silent)**: Run hook with non-dependency path
+13. **PostToolUse Hook - Non-Library (Silent)**:
     ```bash
     echo '{"tool_name": "Read", "tool_input": {"file_path": "/project/src/index.ts"}}' | python3 hooks/posttooluse-bk-reminder.py
     ```
-    - Expected: Empty output (no reminder for non-library paths)
     - PASS if output is empty
 
-14. **Skill Activation Hook - Matching Prompt**: Run hook with library-related question
+14. **Skill Activation Hook - Matching Prompt**:
     ```bash
     export CLAUDE_PLUGIN_ROOT="$(pwd)" && echo '{"prompt": "why does the express package throw this error?"}' | python3 hooks/skill-activation.py
     ```
-    - Expected: JSON output with skill activation reminder for "knowledge-search"
-    - PASS if output contains "MANDATORY EVALUATION" and "knowledge-search"
+    - PASS if output contains "MANDATORY EVALUATION"
 
-15. **Skill Activation Hook - Excluded Prompt**: Run hook with BK command (excluded)
+15. **Skill Activation Hook - Excluded Prompt**:
     ```bash
     export CLAUDE_PLUGIN_ROOT="$(pwd)" && echo '{"prompt": "/bluera-knowledge:search express"}' | python3 hooks/skill-activation.py
     ```
-    - Expected: Empty output (global exclusion matches)
     - PASS if output is empty
 
-16. **Skill Rules File**: Verify skill-rules.json structure
+16. **Skill Rules File**:
     ```bash
     jq -e '(.skills | length) > 0 and (.globalExclusions | length) > 0' hooks/skill-rules.json
     ```
-    - Expected: Returns `true` (valid structure with skills and exclusions)
-    - PASS if command succeeds
-
-### Part 4: Cleanup
+    - PASS if returns `true`
 
-17. **Delete Store**: Call MCP tool `execute` with:
-    ```json
-    { "command": "store:delete", "args": { "store": "bk-test-store" } }
-    ```
-    - Expected: Store deleted
-    - PASS if deletion succeeds
+---
 
-18. **Remove Test Content**: Run bash command:
-    ```bash
-    rm -rf .bluera/bluera-knowledge/test-content
-    ```
-    - Expected: Directory removed
-    - PASS if command succeeds
+## Output Format
 
-19. **Verify Cleanup**: Call MCP tool `execute` with `{ command: "stores" }`
-    - Expected: bk-test-store is NOT in the list
-    - PASS if test store is gone
+### For `--dev` mode (16 tests):
 
-## Output Format
+| # | Test | Status |
+|---|------|--------|
+| 1 | MCP Connection (help) | ? |
+| 2 | List Stores | ? |
+| 3 | Create Store | ? |
+| 4 | Store Info | ? |
+| 5 | Index Store | ? |
+| 6-7 | Search + Get Full Context | ? |
+| 8-10 | Slash Commands | SKIPPED (--dev mode) |
+| 11 | Hook Registration | ? |
+| 12 | PostToolUse - Library Detection | ? |
+| 13 | PostToolUse - Non-Library | ? |
+| 14 | Skill Activation - Matching | ? |
+| 15 | Skill Activation - Excluded | ? |
+| 16 | Skill Rules File | ? |
+| 17 | Delete Store | ? |
+| 18 | Remove Test Content | ? |
+| 19 | Verify Cleanup | ? |
 
-After running all tests, report results in this format:
+**Result: X/16 tests passed (3 skipped)**
 
-### Plugin Test Results
+### For production mode (19 tests):
 
 | # | Test | Status |
 |---|------|--------|
@@ -185,7 +308,7 @@ After running all tests, report results in this format:
 | 10 | /suggest Command | ? |
 | 11 | Hook Registration | ? |
 | 12 | PostToolUse - Library Detection | ? |
-| 13 | PostToolUse - Non-Library (Silent) | ? |
+| 13 | PostToolUse - Non-Library | ? |
 | 14 | Skill Activation - Matching | ? |
 | 15 | Skill Activation - Excluded | ? |
 | 16 | Skill Rules File | ? |
@@ -195,16 +318,18 @@ After running all tests, report results in this format:
 
 **Result: X/19 tests passed**
 
+---
+
 ## Error Recovery
 
 If tests fail partway through, clean up manually:
 
-1. Delete test store (if exists):
-   ```
-   execute → { command: "store:delete", args: { store: "bk-test-store" } }
-   ```
+**In --dev mode:**
+```bash
+node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-store"}}' 2>/dev/null || true
+rm -rf .bluera/bluera-knowledge/test-content
+```
 
-2. Remove test content directory:
-   ```bash
-   rm -rf .bluera/bluera-knowledge/test-content
-   ```
+**In production mode:**
+1. Call MCP tool `execute` with `{ command: "store:delete", args: { store: "bk-test-store" } }`
+2. Run: `rm -rf .bluera/bluera-knowledge/test-content`