bluera-knowledge 0.13.3 → 0.14.1

package/src/logging/payload.ts

@@ -1,119 +0,0 @@
-/**
- * Large payload handling utilities for logging
- *
- * Handles large content (raw HTML, MCP responses) by:
- * - Truncating to preview in log entries
- * - Optionally dumping full content to separate files at trace level
- */
-
-import { createHash } from 'node:crypto';
-import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { getLogDirectory, isLevelEnabled } from './logger.js';
-
-/** Maximum characters for log preview */
-const MAX_PREVIEW_LENGTH = 500;
-
-/** Minimum size to trigger payload dump (10KB) */
-const PAYLOAD_DUMP_THRESHOLD = 10_000;
-
-/** Summary of a large payload for logging */
-export interface PayloadSummary {
-  /** Truncated preview of content */
-  preview: string;
-  /** Size in bytes */
-  sizeBytes: number;
-  /** Short hash for identification */
-  hash: string;
-  /** Filename if full content was dumped (trace level only) */
-  payloadFile?: string;
-}
-
-/** Get the payload dump directory */
-function getPayloadDir(): string {
-  const dir = join(getLogDirectory(), 'payload');
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  return dir;
-}
-
-/** Generate a safe filename from an identifier */
-function safeFilename(identifier: string): string {
-  return identifier.replace(/[^a-zA-Z0-9-]/g, '_').substring(0, 50);
-}
-
-/**
- * Summarize a large payload for logging
- *
- * Creates a summary with:
- * - Truncated preview (first 500 chars)
- * - Size in bytes
- * - Short MD5 hash for identification
- * - Optional full dump to file at trace level
- *
- * @param content - The full content to summarize
- * @param type - Type identifier (e.g., 'raw-html', 'mcp-response')
- * @param identifier - Unique identifier (e.g., URL, query)
- * @param dumpFull - Whether to dump full content to file (default: trace level check)
- * @returns PayloadSummary for inclusion in log entry
- *
- * @example
- * logger.info({
- *   url,
- *   ...summarizePayload(html, 'raw-html', url),
- * }, 'Fetched HTML');
- */
-export function summarizePayload(
-  content: string,
-  type: string,
-  identifier: string,
-  dumpFull: boolean = isLevelEnabled('trace')
-): PayloadSummary {
-  const sizeBytes = Buffer.byteLength(content, 'utf8');
-  const hash = createHash('md5').update(content).digest('hex').substring(0, 12);
-  const preview = truncateForLog(content, MAX_PREVIEW_LENGTH);
-
-  const baseSummary = { preview, sizeBytes, hash };
-
-  // Dump full payload to file if enabled and above threshold
-  if (dumpFull && sizeBytes > PAYLOAD_DUMP_THRESHOLD) {
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const safeId = safeFilename(identifier);
-    const filename = `${timestamp}-${type}-${safeId}-${hash}.json`;
-    const filepath = join(getPayloadDir(), filename);
-
-    writeFileSync(
-      filepath,
-      JSON.stringify(
-        {
-          timestamp: new Date().toISOString(),
-          type,
-          identifier,
-          sizeBytes,
-          content,
-        },
-        null,
-        2
-      )
-    );
-
-    return { ...baseSummary, payloadFile: filename };
-  }
-
-  return baseSummary;
-}
-
-/**
- * Truncate content for logging with ellipsis indicator
- *
- * @param content - Content to truncate
- * @param maxLength - Maximum length (default: 500)
- * @returns Truncated string with '... [truncated]' if needed
- */
-export function truncateForLog(content: string, maxLength: number = MAX_PREVIEW_LENGTH): string {
-  if (content.length <= maxLength) {
-    return content;
-  }
-  return `${content.substring(0, maxLength)}... [truncated]`;
-}

package/src/mcp/cache.test.ts

@@ -1,202 +0,0 @@
-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

@@ -1,103 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * 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 { jobCommands } from './job.commands.js';
-import { metaCommands } from './meta.commands.js';
-import { commandRegistry } from './registry.js';
-import { storeCommands } from './store.commands.js';
-import { syncCommands } from './sync.commands.js';
-
-// Register all commands
-commandRegistry.registerAll(storeCommands);
-commandRegistry.registerAll(jobCommands);
-commandRegistry.registerAll(metaCommands);
-commandRegistry.registerAll(syncCommands);
-
-// 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

@@ -1,48 +0,0 @@
-import { z } from 'zod';
-import { handleCheckJobStatus, handleListJobs, handleCancelJob } from '../handlers/job.handler.js';
-import type { CommandDefinition } from './registry.js';
-import type { CheckJobStatusArgs, ListJobsArgs, CancelJobArgs } from '../schemas/index.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

@@ -1,54 +0,0 @@
-import { z } from 'zod';
-import { commandRegistry, generateHelp } from './registry.js';
-import type { CommandDefinition } from './registry.js';
-import type { ToolResponse } from '../types.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,
-          },
-        ],
-      });
-    },
-  },
-];