bluera-knowledge 0.11.11 → 0.11.13

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.11",
+  "version": "0.11.13",
   "description": "Clone repos, crawl docs, search locally. Fast, authoritative answers for AI coding agents.",
   "mcpServers": {
     "bluera-knowledge": {

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 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.11.13](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.13) (2026-01-10)
+
+
+### Features
+
+* **scripts:** add post-release npm validation script ([e4c29a0](https://github.com/blueraai/bluera-knowledge/commit/e4c29a0c83907de4bc293a69a58412629457fb22))
+* **scripts:** add suggest, sync, serve, mcp tests to npm validation ([49d85da](https://github.com/blueraai/bluera-knowledge/commit/49d85dad1a89691060c12f152d644844baf6e6e6))
+* **scripts:** log expected vs installed version in validation script ([c77d039](https://github.com/blueraai/bluera-knowledge/commit/c77d039b27a3ccf54d50006af161ac4dcfea7b21))
+
+
+### Bug Fixes
+
+* **cli:** plugin-api commands now respect global options ([d3cca02](https://github.com/blueraai/bluera-knowledge/commit/d3cca02ffc679ffc187b76c7682f3cc177eabdea))
+* **plugin:** properly close services after command execution ([eeaf743](https://github.com/blueraai/bluera-knowledge/commit/eeaf743750be73fd9c7a9e72440b2fd0fb5a53fa))
+* **scripts:** show real-time output in validation script ([8a4bdec](https://github.com/blueraai/bluera-knowledge/commit/8a4bdec8b63c504d34ba35bfe19da795f7f7fd07))
+* **scripts:** use mktemp for temp directories in validation script ([3107861](https://github.com/blueraai/bluera-knowledge/commit/3107861bd7a966016fde2a121469dd84756f39be))
+* **search:** add defaults for env vars so CLI works standalone ([b2d2ce5](https://github.com/blueraai/bluera-knowledge/commit/b2d2ce534e8cd2ba0fc0abdac505c912a1a76035))
+
+## [0.11.12](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.12) (2026-01-10)
+
+
+### Features
+
+* **scripts:** add post-release npm validation script ([e4c29a0](https://github.com/blueraai/bluera-knowledge/commit/e4c29a0c83907de4bc293a69a58412629457fb22))
+* **scripts:** add suggest, sync, serve, mcp tests to npm validation ([49d85da](https://github.com/blueraai/bluera-knowledge/commit/49d85dad1a89691060c12f152d644844baf6e6e6))
+* **scripts:** log expected vs installed version in validation script ([c77d039](https://github.com/blueraai/bluera-knowledge/commit/c77d039b27a3ccf54d50006af161ac4dcfea7b21))
+
+
+### Bug Fixes
+
+* **cli:** plugin-api commands now respect global options ([d3cca02](https://github.com/blueraai/bluera-knowledge/commit/d3cca02ffc679ffc187b76c7682f3cc177eabdea))
+* **plugin:** properly close services after command execution ([eeaf743](https://github.com/blueraai/bluera-knowledge/commit/eeaf743750be73fd9c7a9e72440b2fd0fb5a53fa))
+* **scripts:** show real-time output in validation script ([8a4bdec](https://github.com/blueraai/bluera-knowledge/commit/8a4bdec8b63c504d34ba35bfe19da795f7f7fd07))
+* **scripts:** use mktemp for temp directories in validation script ([3107861](https://github.com/blueraai/bluera-knowledge/commit/3107861bd7a966016fde2a121469dd84756f39be))
+* **search:** add defaults for env vars so CLI works standalone ([b2d2ce5](https://github.com/blueraai/bluera-knowledge/commit/b2d2ce534e8cd2ba0fc0abdac505c912a1a76035))
+
 ## [0.11.11](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.11) (2026-01-10)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.11",
+  "version": "0.11.13",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {

package/scripts/validate-npm-release.sh

@@ -213,6 +213,90 @@ else
     pass "Store successfully deleted"
 fi
 
+# Test suggest command
+log_header "Testing suggest"
+
+# Create a minimal package.json for suggest to find
+echo '{"dependencies": {"lodash": "^4.0.0"}}' > "$TEST_FOLDER/package.json"
+run_test "bluera-knowledge suggest" "bluera-knowledge suggest -p '$TEST_FOLDER' -d '$DATA_DIR'"
+
+# Test sync command (should work with no definitions - returns empty result)
+log_header "Testing sync"
+
+run_test_contains "bluera-knowledge sync (no definitions)" "Sync completed" "bluera-knowledge sync -p '$TEST_FOLDER' -d '$DATA_DIR'"
+
+# Test sync with a definitions file
+mkdir -p "$TEST_FOLDER/.bluera/bluera-knowledge"
+cat > "$TEST_FOLDER/.bluera/bluera-knowledge/stores.config.json" << EOF
+{
+  "version": 1,
+  "stores": [
+    {
+      "name": "sync-test-store",
+      "type": "file",
+      "path": "."
+    }
+  ]
+}
+EOF
+run_test "bluera-knowledge sync (with definitions)" "bluera-knowledge sync -p '$TEST_FOLDER' -d '$DATA_DIR'"
+
+# Verify sync created the store
+run_test_contains "Sync created store" "sync-test-store" "bluera-knowledge stores -d '$DATA_DIR'"
+
+# Clean up sync test store
+bluera-knowledge store delete "sync-test-store" --force -d "$DATA_DIR" 2>/dev/null || true
+
+# Test serve command (start, test, stop)
+log_header "Testing serve"
+
+SERVE_PORT=19876
+SERVE_PID=""
+
+# Start server in background
+log "Starting serve on port $SERVE_PORT..."
+bluera-knowledge serve --port $SERVE_PORT -d "$DATA_DIR" &
+SERVE_PID=$!
+
+# Give it time to start
+sleep 2
+
+# Check if server is running
+if kill -0 $SERVE_PID 2>/dev/null; then
+    log "Server started with PID $SERVE_PID"
+
+    # Test health endpoint
+    if curl -s "http://localhost:$SERVE_PORT/health" | grep -q "ok"; then
+        pass "bluera-knowledge serve (health endpoint)"
+    else
+        fail "bluera-knowledge serve (health endpoint not responding)"
+    fi
+
+    # Stop server
+    kill $SERVE_PID 2>/dev/null || true
+    wait $SERVE_PID 2>/dev/null || true
+    log "Server stopped"
+else
+    fail "bluera-knowledge serve (failed to start)"
+fi
+
+# Test mcp command (just verify it starts and outputs JSON-RPC)
+log_header "Testing mcp"
+
+MCP_OUTPUT=$(timeout 2 bluera-knowledge mcp -d "$DATA_DIR" 2>&1 || true)
+if echo "$MCP_OUTPUT" | grep -qE "(jsonrpc|ready|listening|MCP)" 2>/dev/null || [ $? -eq 124 ]; then
+    # Timeout (124) is expected - MCP keeps running until killed
+    pass "bluera-knowledge mcp (starts without error)"
+else
+    # Even if it times out or produces no output, as long as it didn't crash
+    if [ -z "$MCP_OUTPUT" ]; then
+        pass "bluera-knowledge mcp (starts without error)"
+    else
+        log "MCP output: $MCP_OUTPUT"
+        fail "bluera-knowledge mcp (unexpected output)"
+    fi
+fi
+
 # Summary
 log_header "Validation Summary"
 log "Tests run:    $TESTS_RUN"

package/tests/integration/mcp.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
+import { spawn } from 'node:child_process';
+import { rm, mkdtemp, writeFile, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as readline from 'node:readline';
+
+/**
+ * MCP Server Integration Tests
+ *
+ * Tests that the MCP server actually starts and accepts JSON-RPC messages.
+ * Unlike unit tests that mock runMCPServer, these tests spawn a real
+ * MCP server process and communicate via stdin/stdout.
+ */
+describe('MCP Integration', () => {
+  let tempDir: string;
+  let testFilesDir: string;
+
+  beforeAll(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'mcp-test-'));
+    testFilesDir = join(tempDir, 'files');
+    await mkdir(testFilesDir, { recursive: true });
+    await writeFile(
+      join(testFilesDir, 'test.md'),
+      '# Test Document\n\nContent for MCP integration testing.'
+    );
+  }, 30000);
+
+  afterAll(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  interface JSONRPCResponse {
+    jsonrpc: string;
+    id: number;
+    result?: unknown;
+    error?: { code: number; message: string };
+  }
+
+  interface MCPClient {
+    proc: ChildProcess;
+    sendRequest: (method: string, params?: Record<string, unknown>) => Promise<JSONRPCResponse>;
+    close: () => void;
+  }
+
+  /**
+   * Start the MCP server and return a client with message helpers
+   */
+  function startMCPServer(): MCPClient {
+    const proc = spawn('node', ['dist/mcp/server.js'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        PROJECT_ROOT: tempDir,
+        DATA_DIR: join(tempDir, 'data'),
+        CONFIG_PATH: join(tempDir, 'config.json'),
+      },
+    });
+
+    // Set up a single readline interface for the entire process lifetime
+    const rl = readline.createInterface({ input: proc.stdout! });
+    const pendingRequests = new Map<
+      number,
+      { resolve: (r: JSONRPCResponse) => void; reject: (e: Error) => void }
+    >();
+    let requestId = 0;
+
+    rl.on('line', (line: string) => {
+      try {
+        const response = JSON.parse(line) as JSONRPCResponse;
+        const pending = pendingRequests.get(response.id);
+        if (pending !== undefined) {
+          pendingRequests.delete(response.id);
+          pending.resolve(response);
+        }
+      } catch {
+        // Ignore non-JSON lines (like log output)
+      }
+    });
+
+    return {
+      proc,
+      sendRequest: (
+        method: string,
+        params: Record<string, unknown> = {}
+      ): Promise<JSONRPCResponse> => {
+        return new Promise((resolve, reject) => {
+          if (proc.stdin === null) {
+            reject(new Error('Process stdin not available'));
+            return;
+          }
+
+          const id = ++requestId;
+          const timeout = setTimeout(() => {
+            pendingRequests.delete(id);
+            reject(new Error(`Timeout waiting for response to ${method}`));
+          }, 30000);
+
+          pendingRequests.set(id, {
+            resolve: (r) => {
+              clearTimeout(timeout);
+              resolve(r);
+            },
+            reject: (e) => {
+              clearTimeout(timeout);
+              reject(e);
+            },
+          });
+
+          const request = JSON.stringify({
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+          });
+
+          proc.stdin.write(request + '\n');
+        });
+      },
+      close: (): void => {
+        rl.close();
+        proc.kill('SIGTERM');
+      },
+    };
+  }
+
+  /**
+   * Wait for process to be ready
+   */
+  async function waitForReady(client: MCPClient, timeoutMs = 10000): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Timeout waiting for MCP server to start'));
+      }, timeoutMs);
+
+      // MCP servers typically become ready quickly
+      // Give it a moment to initialize
+      setTimeout(() => {
+        clearTimeout(timeout);
+        resolve();
+      }, 1000);
+
+      client.proc.on('error', (err) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+
+      client.proc.on('exit', (code) => {
+        clearTimeout(timeout);
+        if (code !== 0 && code !== null) {
+          reject(new Error(`MCP server exited with code ${code}`));
+        }
+      });
+    });
+  }
+
+  let mcpClient: MCPClient | null = null;
+
+  afterEach(async () => {
+    // Clean up MCP client if still running
+    if (mcpClient !== null) {
+      mcpClient.close();
+      await new Promise<void>((resolve) => {
+        if (mcpClient !== null) {
+          mcpClient.proc.on('exit', () => resolve());
+          setTimeout(() => {
+            if (mcpClient !== null) {
+              mcpClient.proc.kill('SIGKILL');
+            }
+            resolve();
+          }, 2000);
+        } else {
+          resolve();
+        }
+      });
+      mcpClient = null;
+    }
+  });
+
+  it('starts, lists tools, and handles tool execution', async () => {
+    mcpClient = startMCPServer();
+    await waitForReady(mcpClient);
+
+    // 1. Initialize
+    const initResponse = await mcpClient.sendRequest('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'test-client', version: '1.0.0' },
+    });
+
+    expect(initResponse.jsonrpc).toBe('2.0');
+    expect(initResponse.error).toBeUndefined();
+    expect(initResponse.result).toBeDefined();
+
+    const initResult = initResponse.result as {
+      protocolVersion: string;
+      serverInfo: { name: string; version: string };
+      capabilities: { tools: Record<string, unknown> };
+    };
+    expect(initResult.serverInfo.name).toBe('bluera-knowledge');
+    expect(initResult.capabilities.tools).toBeDefined();
+
+    // 2. List tools
+    const toolsResponse = await mcpClient.sendRequest('tools/list', {});
+
+    expect(toolsResponse.error).toBeUndefined();
+    expect(toolsResponse.result).toBeDefined();
+
+    const toolsResult = toolsResponse.result as {
+      tools: Array<{ name: string; description: string }>;
+    };
+    expect(Array.isArray(toolsResult.tools)).toBe(true);
+
+    const toolNames = toolsResult.tools.map((t) => t.name);
+    expect(toolNames).toContain('search');
+    expect(toolNames).toContain('get_full_context');
+    expect(toolNames).toContain('execute');
+
+    // 3. Call search tool
+    const searchResponse = await mcpClient.sendRequest('tools/call', {
+      name: 'search',
+      arguments: {
+        query: 'test query',
+        limit: 5,
+      },
+    });
+
+    expect(searchResponse.error).toBeUndefined();
+    expect(searchResponse.result).toBeDefined();
+
+    const searchResult = searchResponse.result as {
+      content: Array<{ type: string; text: string }>;
+    };
+    expect(Array.isArray(searchResult.content)).toBe(true);
+
+    // 4. Call execute with help command
+    const helpResponse = await mcpClient.sendRequest('tools/call', {
+      name: 'execute',
+      arguments: {
+        command: 'help',
+      },
+    });
+
+    expect(helpResponse.error).toBeUndefined();
+    expect(helpResponse.result).toBeDefined();
+
+    const helpResult = helpResponse.result as { content: Array<{ type: string; text: string }> };
+    expect(helpResult.content[0]?.text).toContain('Available commands');
+  }, 120000);
+});

package/tests/integration/serve.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { rm, mkdtemp, writeFile, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Serve Command Integration Tests
+ *
+ * Tests that the HTTP server actually starts, responds to requests,
+ * and shuts down cleanly. Unlike unit tests that mock the serve function,
+ * these tests spawn a real server process and make actual HTTP requests.
+ */
+describe('Serve Integration', () => {
+  let tempDir: string;
+  let testFilesDir: string;
+  let serverProcess: ChildProcess | null = null;
+  const TEST_PORT = 19877; // Use a unique port to avoid conflicts
+
+  beforeAll(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'serve-test-'));
+    testFilesDir = join(tempDir, 'files');
+    await mkdir(testFilesDir, { recursive: true });
+    await writeFile(
+      join(testFilesDir, 'test.md'),
+      '# Test Document\n\nContent for serve integration testing.'
+    );
+  }, 30000);
+
+  afterAll(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  afterEach(async () => {
+    // Clean up server process if still running
+    if (serverProcess !== null) {
+      serverProcess.kill('SIGTERM');
+      await new Promise<void>((resolve) => {
+        if (serverProcess !== null) {
+          serverProcess.on('exit', () => resolve());
+          // Force kill after timeout
+          setTimeout(() => {
+            if (serverProcess !== null) {
+              serverProcess.kill('SIGKILL');
+            }
+            resolve();
+          }, 2000);
+        } else {
+          resolve();
+        }
+      });
+      serverProcess = null;
+    }
+  });
+
+  /**
+   * Start the serve command and wait for it to be ready
+   */
+  async function startServer(port: number): Promise<ChildProcess> {
+    return new Promise((resolve, reject) => {
+      const proc = spawn(
+        'node',
+        ['dist/index.js', 'serve', '--port', String(port), '--data-dir', tempDir],
+        {
+          stdio: ['pipe', 'pipe', 'pipe'],
+        }
+      );
+
+      let resolved = false;
+      const timeout = setTimeout(() => {
+        if (!resolved) {
+          reject(new Error('Server startup timeout'));
+          proc.kill();
+        }
+      }, 30000);
+
+      proc.stdout?.on('data', (data: Buffer) => {
+        const output = data.toString();
+        if (output.includes('Starting server')) {
+          resolved = true;
+          clearTimeout(timeout);
+          // Give it a moment to actually start listening
+          setTimeout(() => resolve(proc), 500);
+        }
+      });
+
+      proc.stderr?.on('data', (data: Buffer) => {
+        // Log stderr but don't fail - some warnings are expected
+        console.error('Server stderr:', data.toString());
+      });
+
+      proc.on('error', (err) => {
+        if (!resolved) {
+          clearTimeout(timeout);
+          reject(err);
+        }
+      });
+
+      proc.on('exit', (code) => {
+        if (!resolved) {
+          clearTimeout(timeout);
+          reject(new Error(`Server exited with code ${String(code)}`));
+        }
+      });
+    });
+  }
+
+  /**
+   * Make an HTTP request with timeout
+   */
+  async function fetchWithTimeout(
+    url: string,
+    options: RequestInit = {},
+    timeoutMs = 5000
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await fetch(url, { ...options, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  describe('Server Startup and Health', () => {
+    it('starts server and responds to /health', async () => {
+      serverProcess = await startServer(TEST_PORT);
+
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT}/health`);
+      expect(response.ok).toBe(true);
+
+      const body = (await response.json()) as { status: string };
+      expect(body.status).toBe('ok');
+    }, 60000);
+
+    it('responds with CORS headers', async () => {
+      serverProcess = await startServer(TEST_PORT + 1);
+
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 1}/health`, {
+        method: 'OPTIONS',
+        headers: {
+          Origin: 'http://localhost:3000',
+          'Access-Control-Request-Method': 'GET',
+        },
+      });
+
+      // CORS preflight should succeed
+      expect(response.ok).toBe(true);
+    }, 60000);
+  });
+
+  describe('Store API', () => {
+    beforeEach(async () => {
+      serverProcess = await startServer(TEST_PORT + 2);
+    });
+
+    it('lists stores via GET /api/stores', async () => {
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 2}/api/stores`);
+      expect(response.ok).toBe(true);
+
+      const body = (await response.json()) as unknown[];
+      expect(Array.isArray(body)).toBe(true);
+    }, 60000);
+
+    it('creates store via POST /api/stores', async () => {
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 2}/api/stores`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: 'serve-test-store',
+          type: 'file',
+          path: testFilesDir,
+        }),
+      });
+
+      expect(response.status).toBe(201);
+      const body = (await response.json()) as { id: string; name: string };
+      expect(body.name).toBe('serve-test-store');
+      expect(body.id).toBeDefined();
+    }, 60000);
+
+    it('returns 400 for invalid store creation', async () => {
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 2}/api/stores`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: 'invalid-store',
+          type: 'file',
+          // Missing required 'path' for file type
+        }),
+      });
+
+      expect(response.status).toBe(400);
+    }, 60000);
+  });
+
+  describe('Search API', () => {
+    it('handles search request via POST /api/search', async () => {
+      serverProcess = await startServer(TEST_PORT + 3);
+
+      // Search with no stores indexed - should return empty results
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 3}/api/search`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          query: 'test query',
+          limit: 5,
+        }),
+      });
+
+      expect(response.ok).toBe(true);
+      const body = (await response.json()) as { results: unknown[] };
+      expect(body.results).toBeDefined();
+      expect(Array.isArray(body.results)).toBe(true);
+    }, 60000);
+
+    it('returns 400 for invalid search request', async () => {
+      serverProcess = await startServer(TEST_PORT + 4);
+
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 4}/api/search`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          // Missing required 'query'
+        }),
+      });
+
+      expect(response.status).toBe(400);
+    }, 60000);
+  });
+
+  describe('Graceful Shutdown', () => {
+    it('shuts down cleanly on SIGTERM', async () => {
+      serverProcess = await startServer(TEST_PORT + 5);
+
+      // Verify server is running
+      const response = await fetchWithTimeout(`http://127.0.0.1:${TEST_PORT + 5}/health`);
+      expect(response.ok).toBe(true);
+
+      // Send SIGTERM
+      serverProcess.kill('SIGTERM');
+
+      // Wait for process to exit
+      const exitCode = await new Promise<number | null>((resolve) => {
+        if (serverProcess !== null) {
+          serverProcess.on('exit', (code) => resolve(code));
+          // Allow more time for graceful shutdown
+          setTimeout(() => resolve(null), 10000);
+        } else {
+          resolve(null);
+        }
+      });
+
+      // Process should exit cleanly (code 0) or be killed (null)
+      // On some systems the process may not exit with 0 due to async cleanup
+      expect(exitCode === 0 || exitCode === null).toBe(true);
+      serverProcess = null; // Already exited
+    }, 60000);
+  });
+});