bluera-knowledge 0.31.0 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/.claude-plugin/plugin.json +24 -0
  2. package/.mcp.json +13 -0
  3. package/CHANGELOG.md +20 -0
  4. package/NOTICE +47 -0
  5. package/README.md +2 -2
  6. package/bun.lock +1978 -0
  7. package/commands/add-folder.md +48 -0
  8. package/commands/add-repo.md +50 -0
  9. package/commands/cancel.md +63 -0
  10. package/commands/check-status.md +130 -0
  11. package/commands/crawl.md +61 -0
  12. package/commands/doctor.md +27 -0
  13. package/commands/eval.md +222 -0
  14. package/commands/health.md +72 -0
  15. package/commands/index.md +48 -0
  16. package/commands/remove-store.md +52 -0
  17. package/commands/search.md +80 -0
  18. package/commands/search.sh +63 -0
  19. package/commands/skill-activation.md +131 -0
  20. package/commands/stores.md +54 -0
  21. package/commands/suggest.md +118 -0
  22. package/commands/sync.md +96 -0
  23. package/commands/test-plugin.md +547 -0
  24. package/commands/uninstall.md +65 -0
  25. package/dist/{chunk-B335UOU7.js → chunk-3TB7TDVF.js} +24 -3
  26. package/dist/chunk-3TB7TDVF.js.map +1 -0
  27. package/dist/{chunk-KCI4U6FH.js → chunk-KDZDLJUY.js} +2 -2
  28. package/dist/{chunk-AEXFPA57.js → chunk-YDTTD53Y.js} +158 -26
  29. package/dist/chunk-YDTTD53Y.js.map +1 -0
  30. package/dist/index.js +3 -3
  31. package/dist/mcp/bootstrap.js +10 -0
  32. package/dist/mcp/bootstrap.js.map +1 -1
  33. package/dist/mcp/server.d.ts +5 -3
  34. package/dist/mcp/server.js +2 -2
  35. package/dist/workers/background-worker-cli.js +2 -2
  36. package/hooks/check-ready.sh +109 -0
  37. package/hooks/hooks.json +87 -0
  38. package/hooks/job-status-hook.sh +51 -0
  39. package/hooks/posttooluse-bk-reminder.py +126 -0
  40. package/hooks/posttooluse-web-research.py +209 -0
  41. package/hooks/pretooluse-bk-suggest.py +296 -0
  42. package/hooks/skill-activation.py +221 -0
  43. package/hooks/skill-rules.json +131 -0
  44. package/package.json +10 -2
  45. package/scripts/CLAUDE.md +65 -0
  46. package/scripts/auto-setup.sh +65 -0
  47. package/scripts/bench-regression.sh +345 -0
  48. package/scripts/dev.sh +16 -0
  49. package/scripts/doctor.sh +103 -0
  50. package/scripts/download-models.ts +188 -0
  51. package/scripts/export-web-store.ts +142 -0
  52. package/scripts/lib/mock-server.sh +70 -0
  53. package/scripts/mcp-wrapper.sh +91 -0
  54. package/scripts/setup.sh +224 -0
  55. package/scripts/test-mcp-dev.js +260 -0
  56. package/scripts/validate-local.sh +412 -0
  57. package/scripts/validate-npm-release.sh +406 -0
  58. package/skills/advanced-workflows/SKILL.md +273 -0
  59. package/skills/knowledge-search/SKILL.md +110 -0
  60. package/skills/search-optimization/SKILL.md +199 -0
  61. package/skills/search-optimization/references/mistakes.md +21 -0
  62. package/skills/search-optimization/references/strategies.md +80 -0
  63. package/skills/store-lifecycle/SKILL.md +470 -0
  64. package/skills/when-to-query/SKILL.md +160 -0
  65. package/dist/chunk-AEXFPA57.js.map +0 -1
  66. package/dist/chunk-B335UOU7.js.map +0 -1
  67. /package/dist/{chunk-KCI4U6FH.js.map → chunk-KDZDLJUY.js.map} +0 -0
@@ -0,0 +1,547 @@
1
+ ---
2
+ description: Run comprehensive plugin validation test suite
3
+ argument-hint: "[--dev]"
4
+ context: fork
5
+ ---
6
+
7
+ # Test Plugin
8
+
9
+ Comprehensive test of all Bluera Knowledge plugin functionality covering the **full API surface**.
10
+
11
+ ## API Coverage
12
+
13
+ | Category | Tests |
14
+ |----------|-------|
15
+ | MCP execute commands | help, commands, stores, store:create, store:info, store:index, store:delete, stores:health, stores:check-models, stores:sync, stores:pull, jobs, job:status, job:cancel |
16
+ | MCP tools | search, get_full_context |
17
+ | Slash commands | stores, search, suggest, check-status, skill-activation, index, add-folder, health, sync |
18
+ | Web crawling | crawl (start job, verify status, cancel) |
19
+ | Hooks | PostToolUse, UserPromptSubmit, SessionStart |
20
+
21
+ ## When to Use Each Mode
22
+
23
+ | Scenario | Command | Tests |
24
+ |----------|---------|-------|
25
+ | Claude running with `--plugin-dir .` | `/test-plugin` | 38/38 (full suite) |
26
+ | Plugin installed from marketplace | `/test-plugin` | 38/38 (full suite) |
27
+ | Claude running WITHOUT plugin loaded | `/test-plugin --dev` | 29/38 (no slash cmds) |
28
+
29
+ **Modes:**
30
+ - **Default mode**: Uses Claude's MCP tools. Runs all 38 tests including slash commands.
31
+ - **`--dev` mode**: Spawns MCP server directly. Skips slash command tests since they require Claude's skill router.
32
+
33
+ ## Context
34
+
35
+ !`echo "=== BK Plugin Test ===" && ls -la .bluera/bluera-knowledge/ 2>/dev/null || echo "No BK data dir yet (will be created)"`
36
+
37
+ ## Mode Detection
38
+
39
+ Check if `--dev` flag is present in: $ARGUMENTS
40
+
41
+ - If `--dev` is present: Use **Development Mode**
42
+ - Otherwise: Use **Production Mode**
43
+
44
+ ---
45
+
46
+ ## Pre-Test Cleanup
47
+
48
+ Clean up any leftover artifacts from previous test runs (ignore errors):
49
+
50
+ **In `--dev` mode:**
51
+ ```bash
52
+ node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-store"}}' 2>/dev/null || true
53
+ node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-folder"}}' 2>/dev/null || true
54
+ node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-crawl-test"}}' 2>/dev/null || true
55
+ rm -rf .bluera/bluera-knowledge/test-content
56
+ ```
57
+
58
+ **In production mode:**
59
+ 1. Call MCP `execute` with `{ command: "store:delete", args: { store: "bk-test-store" } }` - ignore errors
60
+ 2. Call MCP `execute` with `{ command: "store:delete", args: { store: "bk-test-folder" } }` - ignore errors
61
+ 3. Call MCP `execute` with `{ command: "store:delete", args: { store: "bk-crawl-test" } }` - ignore errors
62
+ 4. Run: `rm -rf .bluera/bluera-knowledge/test-content`
63
+
64
+ ## Test Content Setup
65
+
66
+ Create test content for indexing:
67
+
68
+ ```bash
69
+ mkdir -p .bluera/bluera-knowledge/test-content
70
+ cat > .bluera/bluera-knowledge/test-content/test-file.md << 'EOF'
71
+ # BK Plugin Test File
72
+
73
+ This file contains unique test content for validating the Bluera Knowledge plugin.
74
+
75
+ ## Test Function
76
+
77
+ The `validateBKPlugin` function performs comprehensive testing of all plugin features.
78
+ It checks MCP connectivity, store operations, search functionality, and cleanup.
79
+
80
+ Keywords: bluera-knowledge-test, plugin-validation, mcp-test
81
+ EOF
82
+ ```
83
+
84
+ ---
85
+
86
+ # PRODUCTION MODE (default)
87
+
88
+ Use this section if `--dev` flag is NOT present.
89
+
90
+ ## Part 1: MCP Execute Commands
91
+
92
+ 1. **help**: Call `execute` with `{ command: "help" }`
93
+ - PASS if response contains "Available commands"
94
+
95
+ 2. **commands**: Call `execute` with `{ command: "commands" }`
96
+ - PASS if response contains array of commands including ALL of: "stores", "store:create", "store:info", "store:index", "store:delete", "stores:pull", "stores:check-models", "stores:health", "stores:sync", "jobs", "job:status", "job:cancel", "help", "commands", "uninstall"
97
+
98
+ 3. **stores**: Call `execute` with `{ command: "stores" }`
99
+ - PASS if no error (may return empty array)
100
+
101
+ 4. **store:create**: Call `execute` with:
102
+ ```json
103
+ { "command": "store:create", "args": { "name": "bk-test-store", "type": "file", "source": ".bluera/bluera-knowledge/test-content" } }
104
+ ```
105
+ - PASS if response indicates success and contains store id
106
+
107
+ 5. **store:info**: Call `execute` with:
108
+ ```json
109
+ { "command": "store:info", "args": { "store": "bk-test-store" } }
110
+ ```
111
+ - PASS if response contains store name and type
112
+
113
+ 6. **store:index**: Call `execute` with:
114
+ ```json
115
+ { "command": "store:index", "args": { "store": "bk-test-store" } }
116
+ ```
117
+ - PASS if response indicates indexing started (job created)
118
+
119
+ 7. **jobs**: Call `execute` with `{ command: "jobs" }`
120
+ - PASS if response contains jobs array (may be empty if indexing completed)
121
+
122
+ 8. **job:status** (if job from step 6 available): Call `execute` with:
123
+ ```json
124
+ { "command": "job:status", "args": { "jobId": "<job-id-from-step-6>" } }
125
+ ```
126
+ - PASS if response contains job status (pending, running, or completed)
127
+ - SKIP if no job id available (indexing was synchronous)
128
+
129
+ 9. **stores:health**: Call `execute` with `{ command: "stores:health" }`
130
+ - PASS if response contains health data (no error thrown)
131
+
132
+ 10. **stores:check-models**: Call `execute` with `{ command: "stores:check-models" }`
133
+ - PASS if response contains model compatibility info (no error thrown)
134
+
135
+ 11. **stores:sync** (dry run): Call `execute` with:
136
+ ```json
137
+ { "command": "stores:sync", "args": { "dryRun": true } }
138
+ ```
139
+ - PASS if response contains sync result with skipped/orphans arrays
140
+
141
+ 12. **stores:pull** (error case): Call `execute` with:
142
+ ```json
143
+ { "command": "stores:pull", "args": { "store": "bk-test-store" } }
144
+ ```
145
+ - PASS if response contains error about non-repo store (bk-test-store is type "file", not "repo")
146
+
147
+ ## Part 2: MCP Search Tools
148
+
149
+ 13. **search**: Call MCP tool `search` with:
150
+ ```json
151
+ { "query": "validateBKPlugin", "stores": ["bk-test-store"] }
152
+ ```
153
+ - PASS if results array is non-empty
154
+
155
+ 14. **get_full_context**: Call MCP tool `get_full_context` with resultId from step 13
156
+ - PASS if response contains code or documentation content
157
+
158
+ ## Part 3: Slash Commands
159
+
160
+ 15. **/stores**: Run `/bluera-knowledge:stores`
161
+ - PASS if bk-test-store is listed
162
+
163
+ 16. **/search**: Run `/bluera-knowledge:search "bluera-knowledge-test"`
164
+ - PASS if results are shown
165
+
166
+ 17. **/suggest**: Run `/bluera-knowledge:suggest`
167
+ - PASS if no error thrown
168
+
169
+ 18. **/check-status**: Run `/bluera-knowledge:check-status`
170
+ - PASS if shows job status (may show "no active jobs")
171
+
172
+ 19. **/skill-activation**: Run `/bluera-knowledge:skill-activation`
173
+ - PASS if shows activation configuration or prompts for setup
174
+
175
+ 20. **/index**: Run `/bluera-knowledge:index bk-test-store`
176
+ - PASS if indexing completes or starts successfully
177
+
178
+ 21. **/add-folder**: Run `/bluera-knowledge:add-folder .bluera/bluera-knowledge/test-content --name bk-test-folder`
179
+ - PASS if store creation starts or completes
180
+
181
+ 22. **/health**: Run `/bluera-knowledge:health`
182
+ - PASS if shows health report (no error thrown)
183
+
184
+ 23. **/sync**: Run `/bluera-knowledge:sync --dry-run`
185
+ - PASS if shows sync preview (dry run, no side effects)
186
+
187
+ ## Part 4: Web Crawl Testing
188
+
189
+ > **Note:** Web crawl functionality requires the CLI (`bluera-knowledge crawl`). MCP `store:create` only supports `file` and `repo` types. Skip this section if testing MCP-only environments.
190
+
191
+ 24. **Create web store via CLI** (requires CLI access):
192
+ ```bash
193
+ bluera-knowledge crawl https://httpbin.org/html bk-crawl-test --max-pages 1
194
+ ```
195
+ - PASS if crawl completes and store is created
196
+ - SKIP if CLI not available
197
+
198
+ 25. **Verify store exists**: Call `execute` with `{ command: "stores" }`
199
+ - PASS if bk-crawl-test appears in store list
200
+ - SKIP if test 24 was skipped
201
+
202
+ 26. **job:cancel** (if crawl job still running): Call `execute` with:
203
+ ```json
204
+ { "command": "job:cancel", "args": { "jobId": "<crawl-job-id>" } }
205
+ ```
206
+ - PASS if cancelled or already completed
207
+ - SKIP if test 24 was skipped
208
+
209
+ 27. **Delete crawl store**: Call `execute` with:
210
+ ```json
211
+ { "command": "store:delete", "args": { "store": "bk-crawl-test" } }
212
+ ```
213
+ - PASS if deletion succeeds
214
+ - SKIP if test 24 was skipped
215
+
216
+ ## Part 5: Hook Tests
217
+
218
+ > **Note:** All hook tests use `$CLAUDE_PLUGIN_ROOT` to locate the plugin's hooks directory. This variable is set automatically by Claude Code when running plugin skills.
219
+
220
+ 28. **Hook Registration**:
221
+ ```bash
222
+ jq -e '(.hooks.PostToolUse | length) > 0 and (.hooks.UserPromptSubmit | length) > 0 and (.hooks.SessionStart | length) > 0' "$CLAUDE_PLUGIN_ROOT/hooks/hooks.json"
223
+ ```
224
+ - PASS if returns `true`
225
+
226
+ 29. **PostToolUse Hook - Library Detection**:
227
+ ```bash
228
+ echo '{"tool_name": "Read", "tool_input": {"file_path": "/project/node_modules/express/index.js"}}' | python3 "$CLAUDE_PLUGIN_ROOT/hooks/posttooluse-bk-reminder.py"
229
+ ```
230
+ - PASS if output contains "BLUERA-KNOWLEDGE REMINDER"
231
+
232
+ 30. **PostToolUse Hook - Non-Library**:
233
+ ```bash
234
+ echo '{"tool_name": "Read", "tool_input": {"file_path": "/project/src/index.ts"}}' | python3 "$CLAUDE_PLUGIN_ROOT/hooks/posttooluse-bk-reminder.py"
235
+ ```
236
+ - PASS if output is empty
237
+
238
+ 31. **Skill Activation Hook - Matching**:
239
+ ```bash
240
+ echo '{"prompt": "why does the express package throw this error?"}' | python3 "$CLAUDE_PLUGIN_ROOT/hooks/skill-activation.py"
241
+ ```
242
+ - PASS if output contains "MANDATORY EVALUATION"
243
+
244
+ 32. **Skill Activation Hook - Excluded**:
245
+ ```bash
246
+ echo '{"prompt": "/bluera-knowledge:search express"}' | python3 "$CLAUDE_PLUGIN_ROOT/hooks/skill-activation.py"
247
+ ```
248
+ - PASS if output is empty
249
+
250
+ 33. **Skill Rules File**:
251
+ ```bash
252
+ jq -e '(.skills | length) > 0 and (.globalExclusions | length) > 0' "$CLAUDE_PLUGIN_ROOT/hooks/skill-rules.json"
253
+ ```
254
+ - PASS if returns `true`
255
+
256
+ ## Part 6: Cleanup
257
+
258
+ 34. **Delete test store**: Call `execute` with:
259
+ ```json
260
+ { "command": "store:delete", "args": { "store": "bk-test-store" } }
261
+ ```
262
+ - PASS if deletion succeeds
263
+
264
+ 35. **Delete test folder store**: Call `execute` with:
265
+ ```json
266
+ { "command": "store:delete", "args": { "store": "bk-test-folder" } }
267
+ ```
268
+ - PASS if deletion succeeds or store doesn't exist (created only in production mode by /add-folder)
269
+
270
+ 36. **Remove test content**:
271
+ ```bash
272
+ rm -rf .bluera/bluera-knowledge/test-content
273
+ ```
274
+ - PASS if command succeeds
275
+
276
+ 37. **Verify store cleanup**: Call `execute` with `{ command: "stores" }`
277
+ - PASS if bk-test-store and bk-test-folder are NOT in the list
278
+
279
+ 38. **Verify no test artifacts**:
280
+ ```bash
281
+ test ! -d .bluera/bluera-knowledge/test-content && echo "clean"
282
+ ```
283
+ - PASS if outputs "clean"
284
+
285
+ ---
286
+
287
+ # DEVELOPMENT MODE (`--dev`)
288
+
289
+ Use this section if `--dev` flag is present. Uses `scripts/test-mcp-dev.js`.
290
+
291
+ ### Part 1: MCP Commands (via dev script)
292
+
293
+ 1. **help**:
294
+ ```bash
295
+ node scripts/test-mcp-dev.js call execute '{"command":"help"}'
296
+ ```
297
+ - PASS if contains "Available commands"
298
+
299
+ 2. **commands**:
300
+ ```bash
301
+ node scripts/test-mcp-dev.js call execute '{"command":"commands"}'
302
+ ```
303
+ - PASS if contains commands array including all 15 commands
304
+
305
+ 3. **stores**:
306
+ ```bash
307
+ node scripts/test-mcp-dev.js call execute '{"command":"stores"}'
308
+ ```
309
+ - PASS if no error
310
+
311
+ 4. **store:create**:
312
+ ```bash
313
+ node scripts/test-mcp-dev.js call execute '{"command":"store:create","args":{"name":"bk-test-store","type":"file","source":".bluera/bluera-knowledge/test-content"}}'
314
+ ```
315
+ - PASS if success
316
+
317
+ 5. **store:info**:
318
+ ```bash
319
+ node scripts/test-mcp-dev.js call execute '{"command":"store:info","args":{"store":"bk-test-store"}}'
320
+ ```
321
+ - PASS if contains store details
322
+
323
+ 6. **store:index**:
324
+ ```bash
325
+ node scripts/test-mcp-dev.js call execute '{"command":"store:index","args":{"store":"bk-test-store"}}'
326
+ ```
327
+ - PASS if indexing starts
328
+
329
+ 7. **jobs**:
330
+ ```bash
331
+ node scripts/test-mcp-dev.js call execute '{"command":"jobs"}'
332
+ ```
333
+ - PASS if returns jobs array
334
+
335
+ 8. **job:status** (if job available):
336
+ ```bash
337
+ node scripts/test-mcp-dev.js call execute '{"command":"job:status","args":{"jobId":"<job-id>"}}'
338
+ ```
339
+ - PASS if returns status
340
+
341
+ 9. **stores:health**:
342
+ ```bash
343
+ node scripts/test-mcp-dev.js call execute '{"command":"stores:health"}'
344
+ ```
345
+ - PASS if returns health data
346
+
347
+ 10. **stores:check-models**:
348
+ ```bash
349
+ node scripts/test-mcp-dev.js call execute '{"command":"stores:check-models"}'
350
+ ```
351
+ - PASS if returns model compatibility info
352
+
353
+ 11. **stores:sync** (dry run):
354
+ ```bash
355
+ node scripts/test-mcp-dev.js call execute '{"command":"stores:sync","args":{"dryRun":true}}'
356
+ ```
357
+ - PASS if returns sync result with skipped/orphans
358
+
359
+ 12. **stores:pull** (error case):
360
+ ```bash
361
+ node scripts/test-mcp-dev.js call execute '{"command":"stores:pull","args":{"store":"bk-test-store"}}'
362
+ ```
363
+ - PASS if returns error about non-repo store
364
+
365
+ ### Part 2: Search (via dev script)
366
+
367
+ 13-14. **Search + Get Full Context**:
368
+ ```bash
369
+ node scripts/test-mcp-dev.js session << 'EOF'
370
+ search {"query":"validateBKPlugin","stores":["bk-test-store"]}
371
+ get_full_context {"resultId":"$LAST_ID"}
372
+ EOF
373
+ ```
374
+ - PASS if search returns results and context contains content
375
+
376
+ ### Part 3: Slash Commands (SKIPPED in --dev mode)
377
+
378
+ Tests 15-23 are skipped - slash commands require Claude's skill router.
379
+
380
+ ### Part 4: Web Crawl (via dev script)
381
+
382
+ 24. **Create crawl store**:
383
+ ```bash
384
+ node scripts/test-mcp-dev.js call execute '{"command":"store:create","args":{"name":"bk-crawl-test","type":"web","source":"https://httpbin.org/html","options":{"maxPages":1}}}'
385
+ ```
386
+ - PASS if returns job id
387
+
388
+ 25. **Verify crawl job**:
389
+ ```bash
390
+ node scripts/test-mcp-dev.js call execute '{"command":"jobs"}'
391
+ ```
392
+ - PASS if job appears
393
+
394
+ 26. **job:cancel** (if running):
395
+ ```bash
396
+ node scripts/test-mcp-dev.js call execute '{"command":"job:cancel","args":{"jobId":"<crawl-job-id>"}}'
397
+ ```
398
+ - PASS if cancelled or completed
399
+
400
+ 27. **Delete crawl store**:
401
+ ```bash
402
+ node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-crawl-test"}}'
403
+ ```
404
+ - PASS if deleted
405
+
406
+ ### Part 5: Hook Tests
407
+
408
+ > **Note:** In dev mode, set `CLAUDE_PLUGIN_ROOT` to the current directory (plugin source).
409
+
410
+ 28. **Hook Registration**:
411
+ ```bash
412
+ jq -e '(.hooks.PostToolUse | length) > 0 and (.hooks.UserPromptSubmit | length) > 0 and (.hooks.SessionStart | length) > 0' hooks/hooks.json
413
+ ```
414
+ - PASS if returns `true`
415
+
416
+ 29. **PostToolUse Hook - Library Detection**:
417
+ ```bash
418
+ echo '{"tool_name": "Read", "tool_input": {"file_path": "/project/node_modules/express/index.js"}}' | python3 hooks/posttooluse-bk-reminder.py
419
+ ```
420
+ - PASS if output contains "BLUERA-KNOWLEDGE REMINDER"
421
+
422
+ 30. **PostToolUse Hook - Non-Library**:
423
+ ```bash
424
+ echo '{"tool_name": "Read", "tool_input": {"file_path": "/project/src/index.ts"}}' | python3 hooks/posttooluse-bk-reminder.py
425
+ ```
426
+ - PASS if output is empty
427
+
428
+ 31. **Skill Activation Hook - Matching**:
429
+ ```bash
430
+ CLAUDE_PLUGIN_ROOT="$(pwd)" && echo '{"prompt": "why does the express package throw this error?"}' | python3 hooks/skill-activation.py
431
+ ```
432
+ - PASS if output contains "MANDATORY EVALUATION"
433
+
434
+ 32. **Skill Activation Hook - Excluded**:
435
+ ```bash
436
+ CLAUDE_PLUGIN_ROOT="$(pwd)" && echo '{"prompt": "/bluera-knowledge:search express"}' | python3 hooks/skill-activation.py
437
+ ```
438
+ - PASS if output is empty
439
+
440
+ 33. **Skill Rules File**:
441
+ ```bash
442
+ jq -e '(.skills | length) > 0 and (.globalExclusions | length) > 0' hooks/skill-rules.json
443
+ ```
444
+ - PASS if returns `true`
445
+
446
+ ### Part 6: Cleanup (via dev script)
447
+
448
+ 34. **Delete test store**:
449
+ ```bash
450
+ node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-store"}}'
451
+ ```
452
+ - PASS if deleted
453
+
454
+ 35. **Delete test folder store**:
455
+ ```bash
456
+ node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-folder"}}' 2>/dev/null || true
457
+ ```
458
+ - PASS if deleted or doesn't exist
459
+
460
+ 36. **Remove test content**:
461
+ ```bash
462
+ rm -rf .bluera/bluera-knowledge/test-content
463
+ ```
464
+ - PASS if command succeeds
465
+
466
+ 37. **Verify store cleanup**:
467
+ ```bash
468
+ node scripts/test-mcp-dev.js call execute '{"command":"stores"}'
469
+ ```
470
+ - PASS if bk-test-store and bk-test-folder are NOT in the list
471
+
472
+ 38. **Verify no test artifacts**:
473
+ ```bash
474
+ test ! -d .bluera/bluera-knowledge/test-content && echo "clean"
475
+ ```
476
+ - PASS if outputs "clean"
477
+
478
+ ---
479
+
480
+ ## Output Format
481
+
482
+ ### Production mode (38 tests):
483
+
484
+ | # | Test | Status |
485
+ |---|------|--------|
486
+ | 1 | MCP help | ? |
487
+ | 2 | MCP commands (all 15) | ? |
488
+ | 3 | MCP stores | ? |
489
+ | 4 | MCP store:create | ? |
490
+ | 5 | MCP store:info | ? |
491
+ | 6 | MCP store:index | ? |
492
+ | 7 | MCP jobs | ? |
493
+ | 8 | MCP job:status | ? |
494
+ | 9 | MCP stores:health | ? |
495
+ | 10 | MCP stores:check-models | ? |
496
+ | 11 | MCP stores:sync (dry) | ? |
497
+ | 12 | MCP stores:pull (error) | ? |
498
+ | 13 | MCP search | ? |
499
+ | 14 | MCP get_full_context | ? |
500
+ | 15 | /stores | ? |
501
+ | 16 | /search | ? |
502
+ | 17 | /suggest | ? |
503
+ | 18 | /check-status | ? |
504
+ | 19 | /skill-activation | ? |
505
+ | 20 | /index | ? |
506
+ | 21 | /add-folder | ? |
507
+ | 22 | /health | ? |
508
+ | 23 | /sync | ? |
509
+ | 24 | Crawl store create | ? |
510
+ | 25 | Crawl job verify | ? |
511
+ | 26 | Crawl job:cancel | ? |
512
+ | 27 | Crawl store delete | ? |
513
+ | 28 | Hook registration | ? |
514
+ | 29 | PostToolUse - library | ? |
515
+ | 30 | PostToolUse - non-library | ? |
516
+ | 31 | Skill activation - match | ? |
517
+ | 32 | Skill activation - exclude | ? |
518
+ | 33 | Skill rules file | ? |
519
+ | 34 | Delete test store | ? |
520
+ | 35 | Delete test folder store | ? |
521
+ | 36 | Remove test content | ? |
522
+ | 37 | Verify store cleanup | ? |
523
+ | 38 | Verify no artifacts | ? |
524
+
525
+ **Result: X/38 tests passed**
526
+
527
+ ### Development mode (29 tests):
528
+
529
+ Same table but tests 15-23 show "SKIPPED (--dev mode)"
530
+
531
+ **Result: X/29 tests passed (9 skipped)**
532
+
533
+ ---
534
+
535
+ ## Error Recovery
536
+
537
+ If tests fail partway through, clean up manually:
538
+
539
+ ```bash
540
+ # Delete test stores
541
+ node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-store"}}' 2>/dev/null || true
542
+ node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-folder"}}' 2>/dev/null || true
543
+ node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-crawl-test"}}' 2>/dev/null || true
544
+
545
+ # Remove test content
546
+ rm -rf .bluera/bluera-knowledge/test-content
547
+ ```
@@ -0,0 +1,65 @@
1
+ ---
2
+ description: Remove Bluera Knowledge data from this project
3
+ allowed-tools: ["mcp__bluera-knowledge__execute"]
4
+ ---
5
+
6
+ # Uninstall Bluera Knowledge
7
+
8
+ Remove Bluera Knowledge data from this project.
9
+
10
+ ## Steps
11
+
12
+ 1. Use mcp__bluera-knowledge__execute tool with command "uninstall":
13
+ - Optional args.global: true to also remove global data
14
+ - Optional args.keepDefinitions: false to also remove stores.config.json
15
+
16
+ 2. Display the result showing what was deleted and cleanup instructions.
17
+
18
+ ## Options
19
+
20
+ | Flag | Description |
21
+ |------|-------------|
22
+ | `global` | Also delete global data (~/.local/share/bluera-knowledge/) |
23
+ | `keepDefinitions` | Keep stores.config.json for team sharing (default: true) |
24
+
25
+ ## Examples
26
+
27
+ **Clean project data (preserves stores.config.json):**
28
+ ```
29
+ /bluera-knowledge:uninstall
30
+ ```
31
+
32
+ **Full cleanup including store definitions:**
33
+ ```
34
+ Use uninstall with keepDefinitions: false
35
+ ```
36
+
37
+ **Full cleanup including global data:**
38
+ ```
39
+ Use uninstall with global: true
40
+ ```
41
+
42
+ ## What Gets Deleted
43
+
44
+ **Project data** (`.bluera/bluera-knowledge/`):
45
+ - `data/` - Vector indices, cloned repos, stores.json
46
+ - `config.json` - Plugin configuration
47
+ - `stores.config.json` - Only if keepDefinitions: false
48
+
49
+ **Global data** (with --global flag):
50
+ - `~/.local/share/bluera-knowledge/` - Job history, skill settings
51
+
52
+ ## What Is NOT Deleted
53
+
54
+ - **Plugin cache** - Managed by Claude Code, instructions provided
55
+ - **Python venv** - Inside plugin cache, cleaned when cache is cleared
56
+
57
+ ## Testing Fresh Plugin Installs
58
+
59
+ After running uninstall, to test a completely fresh plugin install:
60
+
61
+ 1. Exit Claude Code
62
+ 2. Clear plugin cache: `rm -rf ~/.claude/plugins/cache/bluera-knowledge-*`
63
+ 3. Restart Claude Code and reinstall the plugin
64
+
65
+ _Clearing the plugin cache removes everything: plugin code, Python venv, and all dependencies._
@@ -4945,6 +4945,7 @@ function mapSearchIntentToQueryIntent(intent) {
4945
4945
  case "find-pattern":
4946
4946
  case "find-implementation":
4947
4947
  case "find-definition":
4948
+ case "find-files":
4948
4949
  return "implementation";
4949
4950
  case "find-usage":
4950
4951
  case "find-documentation":
@@ -5579,6 +5580,12 @@ var SearchService = class {
5579
5580
  location: `${path4}${codeUnit ? `:${String(codeUnit.startLine)}` : ""}`,
5580
5581
  relevanceReason: this.generateRelevanceReason(result, query)
5581
5582
  };
5583
+ if (graph) {
5584
+ const relatedFiles = this.getRelatedFilePaths(graph, path4, symbolName);
5585
+ if (relatedFiles.length > 0) {
5586
+ enhanced.summary = { ...enhanced.summary, relatedFiles };
5587
+ }
5588
+ }
5582
5589
  if (detail === "contextual" || detail === "full") {
5583
5590
  const usage = this.getUsageFromGraph(graph, path4, symbolName);
5584
5591
  enhanced.context = {
@@ -5794,9 +5801,23 @@ var SearchService = class {
5794
5801
  };
5795
5802
  }
5796
5803
  /**
5797
- * Get related code from graph.
5798
- * Returns callers and callees for the symbol.
5804
+ * Get related file paths from code graph edges for follow-up reads.
5805
+ * Returns unique file paths (max 5) from callers/callees, excluding the result's own file.
5799
5806
  */
5807
+ getRelatedFilePaths(graph, filePath, symbolName) {
5808
+ if (symbolName === "" || symbolName === "(anonymous)") return [];
5809
+ const nodeId = `${filePath}:${symbolName}`;
5810
+ const files = /* @__PURE__ */ new Set();
5811
+ for (const edge of graph.getIncomingEdges(nodeId)) {
5812
+ const [file] = this.parseNodeId(edge.from);
5813
+ if (file && file !== filePath) files.add(file);
5814
+ }
5815
+ for (const edge of graph.getEdges(nodeId)) {
5816
+ const [file] = this.parseNodeId(edge.to);
5817
+ if (file && file !== filePath) files.add(file);
5818
+ }
5819
+ return Array.from(files).slice(0, 5);
5820
+ }
5800
5821
  getRelatedCodeFromGraph(graph, filePath, symbolName) {
5801
5822
  if (!graph || symbolName === "" || symbolName === "(anonymous)") {
5802
5823
  return [];
@@ -7555,4 +7576,4 @@ export {
7555
7576
  createServices,
7556
7577
  destroyServices
7557
7578
  };
7558
- //# sourceMappingURL=chunk-B335UOU7.js.map
7579
+ //# sourceMappingURL=chunk-3TB7TDVF.js.map