bluera-knowledge 0.9.21

package/src/index.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createProgram, getGlobalOptions } from './cli/program.js';
+import { createStoreCommand } from './cli/commands/store.js';
+import { createSearchCommand } from './cli/commands/search.js';
+import { createIndexCommand } from './cli/commands/index-cmd.js';
+import { createServeCommand } from './cli/commands/serve.js';
+import { createCrawlCommand } from './cli/commands/crawl.js';
+import { createSetupCommand } from './cli/commands/setup.js';
+import { createMCPCommand } from './cli/commands/mcp.js';
+import { createAddRepoCommand, createAddFolderCommand, createStoresCommand, createSuggestCommand } from './cli/commands/plugin-api.js';
+
+// Default paths
+const DEFAULT_DATA_DIR = join(homedir(), '.bluera', 'bluera-knowledge', 'data');
+const DEFAULT_CONFIG = join(homedir(), '.bluera', 'bluera-knowledge', 'config.json');
+const DEFAULT_REPOS_DIR = join(homedir(), '.bluera', 'bluera-knowledge', 'repos');
+
+/**
+ * Format a command and its subcommands recursively for comprehensive help output.
+ */
+function formatCommandHelp(cmd: Command, indent: string = ''): string[] {
+  const lines: string[] = [];
+  const name = cmd.name();
+  const desc = cmd.description();
+  const args = cmd.registeredArguments.map(a => {
+    const req = a.required;
+    return req ? `<${a.name()}>` : `[${a.name()}]`;
+  }).join(' ');
+
+  // Command header with arguments
+  lines.push(`${indent}${name}${args ? ' ' + args : ''}`);
+  if (desc) {
+    lines.push(`${indent}  ${desc}`);
+  }
+
+  // Options (skip -h, --help which is auto-added)
+  const options = cmd.options.filter(o => o.flags !== '-h, --help');
+  for (const opt of options) {
+    lines.push(`${indent}  ${opt.flags.padEnd(28)} ${opt.description}`);
+  }
+
+  // Subcommands (recursive)
+  const subcommands = cmd.commands.filter(c => c.name() !== 'help');
+  for (const sub of subcommands) {
+    lines.push('');
+    lines.push(...formatCommandHelp(sub, indent + '  '));
+  }
+
+  return lines;
+}
+
+/**
+ * Print comprehensive help showing all commands, subcommands, and options.
+ */
+function printFullHelp(program: Command): void {
+  console.log('bluera-knowledge - CLI tool for managing knowledge stores with semantic search\n');
+
+  // Active paths
+  console.log('Paths:');
+  console.log(`  data        ${DEFAULT_DATA_DIR}`);
+  console.log(`  config      ${DEFAULT_CONFIG}`);
+  console.log(`  repos       ${DEFAULT_REPOS_DIR}`);
+
+  // Global options
+  console.log('\nGlobal options:');
+  const globalOpts = program.options.filter(o => o.flags !== '-h, --help' && o.flags !== '-V, --version');
+  for (const opt of globalOpts) {
+    console.log(`  ${opt.flags.padEnd(28)} ${opt.description}`);
+  }
+
+  console.log('\nCommands:\n');
+
+  // All commands except help
+  const commands = program.commands.filter(c => c.name() !== 'help');
+  for (const cmd of commands) {
+    console.log(formatCommandHelp(cmd).join('\n'));
+    console.log('');
+  }
+}
+
+const program = createProgram();
+
+// Plugin API commands (simple interface)
+program.addCommand(createAddRepoCommand(() => getGlobalOptions(program)));
+program.addCommand(createAddFolderCommand(() => getGlobalOptions(program)));
+program.addCommand(createStoresCommand(() => getGlobalOptions(program)));
+program.addCommand(createSuggestCommand(() => getGlobalOptions(program)));
+
+// Advanced CLI commands
+program.addCommand(createStoreCommand(() => getGlobalOptions(program)));
+program.addCommand(createSearchCommand(() => getGlobalOptions(program)));
+program.addCommand(createIndexCommand(() => getGlobalOptions(program)));
+program.addCommand(createServeCommand(() => getGlobalOptions(program)));
+program.addCommand(createCrawlCommand(() => getGlobalOptions(program)));
+program.addCommand(createSetupCommand(() => getGlobalOptions(program)));
+program.addCommand(createMCPCommand(() => getGlobalOptions(program)));
+
+// Show comprehensive help when no arguments provided
+if (process.argv.length <= 2) {
+  printFullHelp(program);
+  process.exit(0);
+}
+
+program.parse();

package/src/mcp/cache.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect } from 'vitest';
+import { LRUCache } from './cache.js';
+
+describe('LRUCache', () => {
+  describe('constructor', () => {
+    it('should create cache with default max size', () => {
+      const cache = new LRUCache<string, number>();
+      expect(cache.size).toBe(0);
+    });
+
+    it('should create cache with custom max size', () => {
+      const cache = new LRUCache<string, number>(5);
+      expect(cache.size).toBe(0);
+    });
+  });
+
+  describe('set and get', () => {
+    it('should store and retrieve values', () => {
+      const cache = new LRUCache<string, number>(3);
+      cache.set('a', 1);
+      cache.set('b', 2);
+      cache.set('c', 3);
+
+      expect(cache.get('a')).toBe(1);
+      expect(cache.get('b')).toBe(2);
+      expect(cache.get('c')).toBe(3);
+    });
+
+    it('should return undefined for non-existent keys', () => {
+      const cache = new LRUCache<string, number>(3);
+      expect(cache.get('nonexistent')).toBeUndefined();
+    });
+
+    it('should update existing values', () => {
+      const cache = new LRUCache<string, number>(3);
+      cache.set('a', 1);
+      cache.set('a', 100);
+      expect(cache.get('a')).toBe(100);
+    });
+  });
+
+  describe('LRU eviction', () => {
+    it('should evict oldest item when over capacity', () => {
+      const cache = new LRUCache<string, number>(3);
+      cache.set('a', 1);
+      cache.set('b', 2);
+      cache.set('c', 3);
+      cache.set('d', 4); // Evicts 'a'
+
+      expect(cache.get('a')).toBeUndefined();
+      expect(cache.get('b')).toBe(2);
+      expect(cache.get('c')).toBe(3);
+      expect(cache.get('d')).toBe(4);
+    });
+
+    it('should move accessed items to end (most recent)', () => {
+      const cache = new LRUCache<string, number>(3);
+      cache.set('a', 1);
+      cache.set('b', 2);
+      cache.set('c', 3);
+      cache.get('a'); // Access 'a', moves it to end
+      cache.set('d', 4); // Should evict 'b', not 'a'
+
+      expect(cache.get('a')).toBe(1);
+      expect(cache.get('b')).toBeUndefined();
+      expect(cache.get('c')).toBe(3);
+      expect(cache.get('d')).toBe(4);
+    });
+
+    it('should move updated items to end', () => {
+      const cache = new LRUCache<string, number>(3);
+      cache.set('a', 1);
+      cache.set('b', 2);
+      cache.set('c', 3);
+      cache.set('a', 100); // Update 'a', moves it to end
+      cache.set('d', 4); // Should evict 'b', not 'a'
+
+      expect(cache.get('a')).toBe(100);
+      expect(cache.get('b')).toBeUndefined();
+      expect(cache.get('c')).toBe(3);
+      expect(cache.get('d')).toBe(4);
+    });
+  });
+
+  describe('has', () => {
+    it('should return true for existing keys', () => {
+      const cache = new LRUCache<string, number>(3);
+      cache.set('a', 1);
+      expect(cache.has('a')).toBe(true);
+    });
+
+    it('should return false for non-existent keys', () => {
+      const cache = new LRUCache<string, number>(3);
+      expect(cache.has('nonexistent')).toBe(false);
+    });
+  });
+
+  describe('delete', () => {
+    it('should delete existing keys', () => {
+      const cache = new LRUCache<string, number>(3);
+      cache.set('a', 1);
+      cache.set('b', 2);
+
+      expect(cache.delete('a')).toBe(true);
+      expect(cache.has('a')).toBe(false);
+      expect(cache.has('b')).toBe(true);
+      expect(cache.size).toBe(1);
+    });
+
+    it('should return false for non-existent keys', () => {
+      const cache = new LRUCache<string, number>(3);
+      expect(cache.delete('nonexistent')).toBe(false);
+    });
+  });
+
+  describe('clear', () => {
+    it('should remove all entries', () => {
+      const cache = new LRUCache<string, number>(3);
+      cache.set('a', 1);
+      cache.set('b', 2);
+      cache.set('c', 3);
+
+      cache.clear();
+      expect(cache.size).toBe(0);
+      expect(cache.get('a')).toBeUndefined();
+      expect(cache.get('b')).toBeUndefined();
+      expect(cache.get('c')).toBeUndefined();
+    });
+
+    it('should work on empty cache', () => {
+      const cache = new LRUCache<string, number>(3);
+      cache.clear();
+      expect(cache.size).toBe(0);
+    });
+  });
+
+  describe('size', () => {
+    it('should track current size', () => {
+      const cache = new LRUCache<string, number>(5);
+      expect(cache.size).toBe(0);
+
+      cache.set('a', 1);
+      expect(cache.size).toBe(1);
+
+      cache.set('b', 2);
+      expect(cache.size).toBe(2);
+
+      cache.delete('a');
+      expect(cache.size).toBe(1);
+
+      cache.clear();
+      expect(cache.size).toBe(0);
+    });
+
+    it('should not exceed max size', () => {
+      const cache = new LRUCache<string, number>(3);
+      cache.set('a', 1);
+      cache.set('b', 2);
+      cache.set('c', 3);
+      cache.set('d', 4);
+      cache.set('e', 5);
+
+      expect(cache.size).toBe(3);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle capacity of 1', () => {
+      const cache = new LRUCache<string, number>(1);
+      cache.set('a', 1);
+      expect(cache.get('a')).toBe(1);
+
+      cache.set('b', 2);
+      expect(cache.get('a')).toBeUndefined();
+      expect(cache.get('b')).toBe(2);
+    });
+
+    it('should handle storing undefined values', () => {
+      const cache = new LRUCache<string, number | undefined>(3);
+      cache.set('a', undefined);
+      expect(cache.has('a')).toBe(true);
+      expect(cache.get('a')).toBeUndefined();
+    });
+
+    it('should handle complex object values', () => {
+      interface TestObj {
+        id: number;
+        data: string;
+      }
+
+      const cache = new LRUCache<string, TestObj>(3);
+      const obj1 = { id: 1, data: 'test1' };
+      const obj2 = { id: 2, data: 'test2' };
+
+      cache.set('a', obj1);
+      cache.set('b', obj2);
+
+      expect(cache.get('a')).toEqual(obj1);
+      expect(cache.get('b')).toEqual(obj2);
+    });
+  });
+});

package/src/mcp/cache.ts

@@ -0,0 +1,103 @@
+/**
+ * LRU (Least Recently Used) Cache implementation
+ *
+ * Maintains a cache with a maximum size, evicting the oldest (least recently used)
+ * items when the capacity is exceeded. This prevents unbounded memory growth.
+ *
+ * Items are automatically moved to the end of the cache when accessed (via get),
+ * making them the most recently used.
+ */
+export class LRUCache<K, V> {
+  private readonly cache = new Map<K, V>();
+  private readonly maxSize: number;
+
+  /**
+   * Create a new LRU cache
+   *
+   * @param maxSize - Maximum number of items to store (default: 1000)
+   */
+  constructor(maxSize: number = 1000) {
+    this.maxSize = maxSize;
+  }
+
+  /**
+   * Store a value in the cache
+   *
+   * If the key already exists, it will be moved to the end (most recent).
+   * If the cache is at capacity, the oldest item will be evicted.
+   *
+   * @param key - The cache key
+   * @param value - The value to store
+   */
+  set(key: K, value: V): void {
+    // If key exists, delete it first to move it to the end
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    // Add the new/updated entry
+    this.cache.set(key, value);
+
+    // Evict oldest entry if over capacity
+    if (this.cache.size > this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
+    }
+  }
+
+  /**
+   * Retrieve a value from the cache
+   *
+   * If the key exists, it will be moved to the end (most recent).
+   *
+   * @param key - The cache key
+   * @returns The cached value, or undefined if not found
+   */
+  get(key: K): V | undefined {
+    const value = this.cache.get(key);
+
+    if (value !== undefined) {
+      // Move to end (most recent) by deleting and re-adding
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+
+    return value;
+  }
+
+  /**
+   * Check if a key exists in the cache
+   *
+   * @param key - The cache key
+   * @returns True if the key exists
+   */
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+
+  /**
+   * Remove a specific key from the cache
+   *
+   * @param key - The cache key
+   * @returns True if the key was removed, false if it didn't exist
+   */
+  delete(key: K): boolean {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all entries from the cache
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get the current number of items in the cache
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+}

package/src/mcp/commands/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Command registration for the execute meta-tool
+ *
+ * This module registers all commands with the command registry.
+ * Import this module to ensure all commands are available.
+ */
+
+import { commandRegistry } from './registry.js';
+import { storeCommands } from './store.commands.js';
+import { jobCommands } from './job.commands.js';
+import { metaCommands } from './meta.commands.js';
+
+// Register all commands
+commandRegistry.registerAll(storeCommands);
+commandRegistry.registerAll(jobCommands);
+commandRegistry.registerAll(metaCommands);
+
+// Re-export for convenience
+export { commandRegistry, executeCommand, generateHelp } from './registry.js';
+export type { CommandDefinition, CommandHandler } from './registry.js';

package/src/mcp/commands/job.commands.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import type { CommandDefinition } from './registry.js';
+import type {
+  CheckJobStatusArgs,
+  ListJobsArgs,
+  CancelJobArgs
+} from '../schemas/index.js';
+import {
+  handleCheckJobStatus,
+  handleListJobs,
+  handleCancelJob
+} from '../handlers/job.handler.js';
+
+/**
+ * Job management commands for the execute meta-tool
+ *
+ * These commands wrap the existing job handlers, providing
+ * a unified interface through the execute command.
+ *
+ * Note: Type assertions are necessary here because CommandHandler uses
+ * Record<string, unknown> for generic command args, while handlers expect
+ * specific typed args. Zod validates at runtime before the cast.
+ */
+/* eslint-disable @typescript-eslint/consistent-type-assertions */
+export const jobCommands: CommandDefinition[] = [
+  {
+    name: 'jobs',
+    description: 'List all background jobs',
+    argsSchema: z.object({
+      activeOnly: z.boolean().optional().describe('Only show active jobs'),
+      status: z.enum(['pending', 'running', 'completed', 'failed', 'cancelled'])
+        .optional()
+        .describe('Filter by job status')
+    }),
+    handler: (args, context) => handleListJobs(args as unknown as ListJobsArgs, context)
+  },
+  {
+    name: 'job:status',
+    description: 'Check the status of a specific background job',
+    argsSchema: z.object({
+      jobId: z.string().min(1).describe('Job ID to check')
+    }),
+    handler: (args, context) => handleCheckJobStatus(args as unknown as CheckJobStatusArgs, context)
+  },
+  {
+    name: 'job:cancel',
+    description: 'Cancel a running or pending background job',
+    argsSchema: z.object({
+      jobId: z.string().min(1).describe('Job ID to cancel')
+    }),
+    handler: (args, context) => handleCancelJob(args as unknown as CancelJobArgs, context)
+  }
+];
+/* eslint-enable @typescript-eslint/consistent-type-assertions */

package/src/mcp/commands/meta.commands.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import type { CommandDefinition } from './registry.js';
+import type { ToolResponse } from '../types.js';
+import { commandRegistry, generateHelp } from './registry.js';
+
+/**
+ * Meta commands for introspection and help
+ *
+ * These commands provide self-documentation for the execute tool,
+ * allowing users to discover available commands and their usage.
+ */
+export const metaCommands: CommandDefinition[] = [
+  {
+    name: 'commands',
+    description: 'List all available commands',
+    handler: (): Promise<ToolResponse> => {
+      const commands = commandRegistry.all();
+      const commandList = commands.map(cmd => ({
+        name: cmd.name,
+        description: cmd.description
+      }));
+
+      return Promise.resolve({
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify({ commands: commandList }, null, 2)
+          }
+        ]
+      });
+    }
+  },
+  {
+    name: 'help',
+    description: 'Show help for a specific command or list all commands',
+    argsSchema: z.object({
+      command: z.string().optional().describe('Command name to get help for')
+    }),
+    handler: (args: Record<string, unknown>): Promise<ToolResponse> => {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      const commandName = args['command'] as string | undefined;
+      const helpText = generateHelp(commandName);
+
+      return Promise.resolve({
+        content: [
+          {
+            type: 'text' as const,
+            text: helpText
+          }
+        ]
+      });
+    }
+  }
+];