bluera-knowledge 0.36.0 → 0.37.1

package/scripts/preview-ui.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env bun
+/**
+ * Preview mcp-ui HTML views in a browser.
+ *
+ * Usage: bun run preview:ui [stores|search]
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { renderStoresDashboard } from '../src/mcp/ui/stores-dashboard.js';
+import { renderSearchResults } from '../src/mcp/ui/search-results.js';
+
+const view = process.argv[2] ?? 'stores';
+const outDir = join(import.meta.dirname, '..', '.preview');
+mkdirSync(outDir, { recursive: true });
+
+if (view === 'stores') {
+  const html = renderStoresDashboard([
+    {
+      id: 'abc-123',
+      name: 'mcp-ui',
+      type: 'repo',
+      url: 'https://github.com/MCP-UI-Org/mcp-ui',
+      branch: 'main',
+      modelId: 'Xenova/bge-small-en-v1.5',
+      createdAt: new Date(Date.now() - 2 * 86400000).toISOString(),
+      tags: ['sdk', 'ui', 'mcp'],
+      description: 'MCP UI SDK for building interactive web components over MCP',
+    },
+    {
+      id: 'def-456',
+      name: 'react',
+      type: 'repo',
+      url: 'https://github.com/facebook/react',
+      branch: 'main',
+      modelId: 'Xenova/bge-small-en-v1.5',
+      createdAt: new Date(Date.now() - 30 * 86400000).toISOString(),
+      tags: ['frontend', 'framework'],
+      description: 'The library for web and native user interfaces',
+    },
+    {
+      id: 'ghi-789',
+      name: 'project-docs',
+      type: 'file',
+      path: '/Users/dev/repos/my-project/docs',
+      createdAt: new Date(Date.now() - 1 * 86400000).toISOString(),
+      description: 'Local project documentation',
+    },
+    {
+      id: 'jkl-012',
+      name: 'mdn-web-apis',
+      type: 'web',
+      url: 'https://developer.mozilla.org/en-US/docs/Web/API',
+      createdAt: new Date(Date.now() - 7 * 86400000).toISOString(),
+      tags: ['docs', 'web-apis'],
+      description: 'MDN Web API reference documentation',
+    },
+    {
+      id: 'mno-345',
+      name: 'pending-store',
+      type: 'repo',
+      url: 'https://github.com/example/lib',
+      createdAt: new Date().toISOString(),
+      description: 'A store still being indexed',
+    },
+  ]);
+
+  const outFile = join(outDir, 'stores.html');
+  writeFileSync(outFile, html);
+  console.log(`Wrote ${outFile}`);
+  execSync(`open "${outFile}"`);
+} else if (view === 'search') {
+  const html = renderSearchResults(
+    'createUIResource options and usage',
+    [
+      {
+        id: 'r1',
+        score: 0.92,
+        summary: {
+          type: 'function',
+          name: 'createUIResource',
+          signature: 'function createUIResource(options: CreateUIResourceOptions): UIResource',
+          purpose: 'Creates a UIResource object to include in MCP tool result content arrays',
+          location: 'sdks/typescript/server/src/index.ts:32',
+          relevanceReason: 'Matches: createUIResource, options, usage',
+          storeName: 'mcp-ui',
+        },
+        context: {
+          interfaces: ['CreateUIResourceOptions', 'UIResource'],
+          keyImports: ['@modelcontextprotocol/ext-apps'],
+          relatedConcepts: ['rawHtml', 'externalUrl', 'encoding', 'mimeType'],
+          usage: { calledBy: 12, calls: 3 },
+        },
+        full: {
+          completeCode: `export async function createUIResource(options: CreateUIResourceOptions): Promise<UIResource> {
+  let actualContentString: string;
+  const mimeType: MimeType = RESOURCE_MIME_TYPE;
+
+  if (!options.uri.startsWith('ui://')) {
+    throw new Error("MCP-UI SDK: URI must start with 'ui://'.");
+  }
+
+  if (options.content.type === 'rawHtml') {
+    actualContentString = options.content.htmlString;
+  } else if (options.content.type === 'externalUrl') {
+    actualContentString = await fetchExternalUrl(options.content.iframeUrl);
+  }
+  // ...
+}`,
+          documentation: 'Creates a UIResource for inclusion in tool results.',
+          relatedCode: [
+            {
+              file: 'types.ts',
+              summary: 'Type definitions for CreateUIResourceOptions',
+              relationship: 'defines input types',
+            },
+          ],
+        },
+      },
+      {
+        id: 'r2',
+        score: 0.78,
+        summary: {
+          type: 'interface',
+          name: 'CreateUIResourceOptions',
+          signature: 'interface CreateUIResourceOptions',
+          purpose: 'Configuration options for creating a UI resource',
+          location: 'sdks/typescript/server/src/types.ts:15',
+          relevanceReason: 'Matches: options, createUIResource',
+          storeName: 'mcp-ui',
+        },
+        context: {
+          interfaces: ['ResourceContentPayload'],
+          keyImports: [],
+          relatedConcepts: ['uri', 'content', 'encoding', 'embeddedResourceProps'],
+        },
+      },
+      {
+        id: 'r3',
+        score: 0.65,
+        summary: {
+          type: 'documentation',
+          name: 'Server Walkthrough',
+          purpose: 'Step-by-step guide for integrating mcp-ui into an MCP server',
+          location: 'docs/src/guide/server/typescript/walkthrough.md',
+          relevanceReason: 'Matches: usage, createUIResource',
+          storeName: 'mcp-ui',
+        },
+      },
+      {
+        id: 'r4',
+        score: 0.41,
+        summary: {
+          type: 'const',
+          name: 'RESOURCE_MIME_TYPE',
+          signature: "const RESOURCE_MIME_TYPE = 'text/html;profile=mcp-app'",
+          purpose: 'Standard MIME type for MCP UI resources',
+          location: 'sdks/typescript/server/src/types.ts:3',
+          storeName: 'mcp-ui',
+        },
+      },
+      {
+        id: 'r5',
+        score: 0.33,
+        summary: {
+          type: 'example',
+          name: 'showRawHtml tool',
+          purpose: 'Example tool handler returning a raw HTML UI resource',
+          location: 'examples/typescript-server-demo/src/index.ts:79',
+          relevanceReason: 'Matches: usage example of createUIResource',
+          storeName: 'mcp-ui',
+        },
+        full: {
+          completeCode: `server.registerTool('showRawHtml', {
+  title: 'Show Raw HTML',
+  description: 'Creates a UI resource displaying raw HTML.',
+  inputSchema: {},
+}, async () => {
+  const uiResource = await createUIResource({
+    uri: 'ui://raw-html-demo',
+    content: { type: 'rawHtml', htmlString: '<h1>Hello from Raw HTML</h1>' },
+    encoding: 'text',
+  });
+  return { content: [uiResource] };
+});`,
+        },
+      },
+    ],
+    {
+      timeMs: 29,
+      confidence: 'high',
+      mode: 'hybrid',
+      stores: {
+        'mcp-ui': { type: 'repo', url: 'https://github.com/MCP-UI-Org/mcp-ui' },
+      },
+    }
+  );
+
+  const outFile = join(outDir, 'search.html');
+  writeFileSync(outFile, html);
+  console.log(`Wrote ${outFile}`);
+  execSync(`open "${outFile}"`);
+} else {
+  console.error(`Unknown view: ${view}. Use "stores" or "search".`);
+  process.exit(1);
+}

package/skills/advanced-workflows/references/combining-workflows.md

@@ -0,0 +1,17 @@
+# Combining Workflows
+
+Real-world usage often combines these patterns:
+
+```
+User: "I need to understand how Express and Hono handle middleware differently"
+
+1. list_stores() → check if both indexed
+2. If not: create_store() for missing framework(s)
+3. check_job_status() → wait for indexing
+4. search("middleware implementation", stores=['express', 'hono'], detail='minimal')
+5. Review summaries, identify key files
+6. get_full_context() for 2-3 most relevant from each framework
+7. Compare implementations with full context
+```
+
+This multi-step workflow is efficient, targeted, and conserves context.

package/skills/advanced-workflows/references/error-recovery.md

@@ -0,0 +1,44 @@
+# Error Recovery
+
+When operations fail, use these recovery patterns:
+
+### Workflow: Handle Indexing Failures
+
+```
+1. create_store() fails or job_status shows 'failed'
+   → Check error message
+   → Common issues:
+     - Git auth required (private repo)
+     - Invalid URL/path
+     - Disk space
+     - Network timeout
+
+2. Recovery actions:
+   - Auth issue: Provide credentials or use HTTPS
+   - Invalid path: Verify URL/path exists
+   - Disk space: delete_store() unused stores
+   - Network: Retry with smaller repo or use --shallow
+
+3. Verify recovery:
+   list_stores() → Check store appeared
+   search(test_query, stores=[new_store]) → Verify searchable
+```
+
+**Example:**
+
+```
+create_store('https://github.com/private/repo', 'my-repo')
+→ job_id: 'job_xyz'
+
+check_job_status('job_xyz')
+→ Status: failed
+→ Error: "Authentication required for private repository"
+
+# Recovery: Use authenticated URL or SSH
+create_store('git@github.com:private/repo.git', 'my-repo')
+→ job_id: 'job_xyz2'
+
+check_job_status('job_xyz2')
+→ Status: completed
+→ Success!
+```

package/skills/advanced-workflows/references/handling-large-results.md

@@ -0,0 +1,48 @@
+# Handling Large Result Sets
+
+When initial search returns many results, use progressive detail to avoid context overload:
+
+### Workflow: Progressive Detail Strategy
+
+```
+1. search(query, detail='minimal', limit=20)
+   → Get summaries only (~100 tokens/result)
+   → Review all 20 summaries quickly
+
+2. Filter by relevance score:
+   - Score > 0.8: Excellent match
+   - Score 0.6-0.8: Good match
+   - Score < 0.6: Possibly irrelevant
+
+3. For top 3-5 results (score > 0.7):
+   get_full_context(selected_ids)
+   → Fetch complete code only for relevant items
+   → Saves ~80% context vs fetching all upfront
+
+4. If nothing relevant:
+   search(refined_query, detail='contextual', limit=10)
+   → Try different query with more context
+   → Or broaden/narrow the search
+```
+
+**Example:**
+
+```
+# Initial broad search
+search("authentication middleware", detail='minimal', limit=20)
+→ 20 results, scores ranging 0.45-0.92
+→ Total context: ~2k tokens (minimal)
+
+# Filter by score
+Top results (>0.7):
+  - Result 3: auth/jwt.ts (score: 0.92)
+  - Result 7: middleware/authenticate.ts (score: 0.85)
+  - Result 12: auth/session.ts (score: 0.74)
+
+# Get full code for top 3 only
+get_full_context(['result_3', 'result_7', 'result_12'])
+→ Complete implementations for relevant files only
+→ Context: ~3k tokens (vs ~15k if we fetched all 20)
+
+# Found what we needed! If not, would refine query and retry.
+```

package/skills/advanced-workflows/references/multi-store-search.md

@@ -0,0 +1,42 @@
+# Multi-Store Search with Ranking
+
+When searching across multiple stores, use ranking to prioritize results:
+
+### Workflow: Cross-Library Search
+
+```
+1. search(query, limit=10)
+   → Searches ALL stores
+   → Returns mixed results ranked by relevance
+
+2. Review store distribution:
+   - If dominated by one store: might narrow to specific stores
+   - If balanced: good cross-library perspective
+
+3. For specific library focus:
+   search(query, stores=['lib1', 'lib2'], limit=15)
+   → Search only relevant libraries
+   → Get more results from target libraries
+```
+
+**Example:**
+
+User: "How do different frameworks handle routing?"
+
+```
+# Search all indexed frameworks
+search("routing implementation", intent='find-implementation', limit=15)
+→ Result mix:
+  - express (score: 0.91)
+  - fastapi (score: 0.89)
+  - hono (score: 0.87)
+  - vue-router (score: 0.82)
+  - ...
+
+# All stores represented, good comparative view!
+
+# If user wants deeper FastAPI focus:
+search("routing implementation", stores=['fastapi', 'starlette'], limit=20)
+→ More FastAPI/Starlette-specific results
+→ Deeper exploration of Python framework routing
+```

package/skills/search/statusline.md

@@ -0,0 +1,75 @@
+---
+description: Add bluera-knowledge status indicator to the statusline
+allowed-tools: [Read, Edit, Write, Bash]
+---
+
+# Bluera Knowledge Statusline
+
+Add a 📘 blue book icon with MCP connectivity LED to the Claude Code statusline.
+
+## What it shows
+
+- `📘●` (green) — MCP server process is running
+- `📘●` (red) — MCP server not detected
+
+## Instructions
+
+### 1. Check if already installed
+
+```bash
+grep -c "# --- bluera-knowledge ---" ~/.claude/statusline.sh 2>/dev/null
+```
+
+**If the count is >= 1: already installed.** Tell the user it's already present and stop. Do NOT inject again.
+
+**If 0 or file missing:** proceed to install.
+
+### 2. Read the current statusline
+
+```bash
+cat ~/.claude/statusline.sh
+```
+
+If the file doesn't exist, create a minimal statusline with just the BK module.
+
+### 3. Inject the module
+
+Read the module from the plugin:
+
+```bash
+cat "${CLAUDE_PLUGIN_ROOT:-.}/scripts/statusline-module.sh"
+```
+
+Insert the block between `# --- bluera-knowledge ---` and `# --- end bluera-knowledge ---` into `~/.claude/statusline.sh`:
+
+- Place the function **before** the final output `printf`/`echo` statement(s)
+- Place it **after** other module functions (like `get_bluera_status`, `get_project_type`, etc.)
+- The leading space in the printf output is intentional — it separates from the previous badge
+
+### 4. Wire into the output
+
+Find the output `printf` lines (there are typically 3 — one per context color threshold). Add `%s` and `"$BK_STATUS"` to each, positioned **after** `"$BLUERA_STATUS"` and **before** `"$GIT_INFO"`.
+
+For example, if the current format is:
+```bash
+printf "... %s%s%s ..." "$PROJECT_TYPE" "$BLUERA_STATUS" "$GIT_INFO" ...
+```
+
+Change to:
+```bash
+printf "... %s%s%s%s ..." "$PROJECT_TYPE" "$BLUERA_STATUS" "$BK_STATUS" "$GIT_INFO" ...
+```
+
+**Important:** Add exactly one `%s` to each format string AND one `"$BK_STATUS"` to each argument list. Count the format specifiers vs arguments to ensure they match.
+
+### 5. Verify
+
+```bash
+bash -n ~/.claude/statusline.sh && echo "Syntax OK"
+```
+
+### 6. Edge cases
+
+- **No statusline.sh exists**: Create a minimal one that reads stdin, runs `get_bk_status`, and echoes the result
+- **Non-bluera preset**: Find the output `echo`/`printf` and append `$BK_STATUS` to it
+- **No `$BLUERA_STATUS` in output**: Place `$BK_STATUS` at the end of the output, before any separators

package/skills/store-lifecycle/references/failure-recovery.md

@@ -0,0 +1,80 @@
+# Handling Indexing Failures
+
+### Common Failure Scenarios
+
+**1. Authentication Required (Private Repos)**
+```
+Error: "Authentication required"
+
+Fix options:
+  - Use SSH URL: git@github.com:org/repo.git
+  - Use HTTPS with token: https://token@github.com/org/repo.git
+  - Make repo public (if appropriate)
+```
+
+**2. Invalid URL/Path**
+```
+Error: "Repository not found" or "Path does not exist"
+
+Fix:
+  - Verify URL is correct (typos common!)
+  - Check path exists and is accessible
+  - Ensure network connectivity
+```
+
+**3. Disk Space**
+```
+Error: "No space left on device"
+
+Fix:
+  - Check available space: df -h
+  - Delete unused stores: delete_store(old_store)
+  - Clear .bluera/bluera-knowledge/repos/ manually if needed
+```
+
+**4. Network Timeout**
+```
+Error: "Connection timeout" or "Failed to fetch"
+
+Fix:
+  - Retry after checking network
+  - Use --shallow for large repos
+  - Clone manually then add-folder
+```
+
+**5. Unsupported File Types**
+```
+Warning: "Skipped 45 binary files"
+
+This is normal!
+  - Binary files (images, compiled code) are skipped
+  - Only text files are indexed
+  - Check indexed count vs total to see ratio
+```
+
+### Recovery Workflow
+
+```
+1. Attempt fails:
+   create_store(url, name) → job fails
+
+2. Check error:
+   job_status = check_job_status(job_id)
+   error_msg = job_status['error']
+
+3. Determine fix based on error type (see above)
+
+4. Retry with fix:
+   create_store(corrected_url, name)
+
+5. Verify success:
+   check_job_status(new_job_id)
+   → Status: completed
+
+   list_stores()
+   → Store appears in list
+
+6. Test search:
+   search(test_query, stores=[name], limit=3)
+   → Returns results: Ready to use!
+```

package/skills/store-lifecycle/references/indexing-strategies.md

@@ -0,0 +1,67 @@
+# Indexing Strategies
+
+### Initial Indexing
+
+When creating a store, indexing happens automatically in the background:
+
+```
+create_store(url, name)
+→ Returns: job_id
+→ Background: clone/download → analyze → index
+→ Status: pending → running → completed
+
+# Monitor progress
+check_job_status(job_id)
+→ Progress: 45% (processing src/core.ts)
+→ Estimated: ~2 minutes remaining
+```
+
+**Indexing time estimates:**
+- Small library (<1k files): 30-60 seconds
+- Medium library (1k-5k files): 1-3 minutes
+- Large library (>5k files): 3-10 minutes
+- Documentation crawl (100 pages): 1-2 minutes
+
+### Re-indexing (Updates)
+
+When library code changes or you modify indexed content:
+
+```
+# For git repos: pull latest changes
+cd .bluera/bluera-knowledge/repos/vue
+git pull origin main
+cd -
+
+# Re-index
+/bluera-knowledge:index vue
+
+# Or via MCP:
+index_store(store='vue')
+→ Re-processes all files
+→ Updates vector embeddings
+→ Rebuilds search index
+```
+
+**When to re-index:**
+- Library released new version
+- You modified local folder content
+- Search results seem outdated
+- After significant codebase changes
+
+**Re-indexing is incremental** - only changed files are re-processed.
+
+### Selective Indexing
+
+For large repos, you might want to index specific directories:
+
+```
+# Clone full repo manually
+git clone https://github.com/microsoft/vscode
+cd vscode
+
+# Index only specific dirs
+/bluera-knowledge:add-folder ./src/vs/editor --name=vscode-editor
+/bluera-knowledge:add-folder ./src/vs/workbench --name=vscode-workbench
+
+# Result: Multiple focused stores instead of one massive store
+```

package/skills/store-lifecycle/references/job-monitoring.md

@@ -0,0 +1,72 @@
+# Background Job Monitoring
+
+All expensive operations run as background jobs: cloning, indexing, crawling.
+
+### Job Lifecycle
+
+```
+1. create_store() or index_store() → Returns job_id
+
+2. Job states:
+   - pending: In queue, not started
+   - running: Actively processing
+   - completed: Finished successfully
+   - failed: Error occurred
+
+3. Monitor progress:
+   check_job_status(job_id)
+   → Current state, percentage, current file
+
+4. List all jobs:
+   list_jobs()
+   → See pending, running, completed jobs
+
+5. Cancel if needed:
+   cancel_job(job_id)
+   → Stops running job, cleans up
+```
+
+### Best Practices for Job Monitoring
+
+**Do poll, but not too frequently:**
+```
+# Too frequent - wastes resources
+while status != 'completed':
+    check_job_status(job_id)  # Every second!
+    sleep(1)
+
+# Reasonable polling interval
+while status != 'completed':
+    check_job_status(job_id)
+    sleep(15)  # Every 15 seconds is fine
+```
+
+**Do handle failures gracefully:**
+```
+status = check_job_status(job_id)
+
+if status['state'] == 'failed':
+    error = status['error']
+
+    if 'auth' in error.lower():
+        print("Authentication required - try SSH URL or provide credentials")
+    elif 'not found' in error.lower():
+        print("Repository/URL not found - check the source")
+    elif 'disk' in error.lower():
+        print("Disk space issue - delete unused stores")
+    else:
+        print(f"Unexpected error: {error}")
+```
+
+**Do list jobs to avoid duplicates:**
+```
+# Before creating new store
+jobs = list_jobs()
+existing = [j for j in jobs if j['store'] == 'vue' and j['state'] in ['pending', 'running']]
+
+if existing:
+    print(f"Job already running for 'vue': {existing[0]['id']}")
+    # Wait for it instead of creating duplicate
+else:
+    create_store(...)
+```

package/skills/store-lifecycle/references/lifecycle-checklist.md

@@ -0,0 +1,20 @@
+# Store Lifecycle Checklist
+
+**Creating a Store:**
+- [ ] Choose appropriate source type (repo/folder/crawl)
+- [ ] Use descriptive, consistent naming
+- [ ] Start indexing job
+- [ ] Monitor job status until complete
+- [ ] Verify with list_stores()
+- [ ] Test with sample search
+
+**Maintaining a Store:**
+- [ ] Re-index after significant changes
+- [ ] Pull git updates periodically for repo stores
+- [ ] Monitor storage usage
+- [ ] Check search relevance quality
+
+**Deleting a Store:**
+- [ ] Confirm no longer needed
+- [ ] Note storage freed
+- [ ] Remove from any documentation referencing it