@nahisaho/shikigami-mcp-server 1.7.0 → 1.10.0

package/src/cache/global.ts

@@ -0,0 +1,351 @@
+/**
+ * Global Cache Store
+ * v1.0.0 - REQ-CACHE-001-03
+ *
+ * ユーザー横断のグローバルキャッシュを管理
+ * ~/.shikigami/global-cache/ に保存
+ */
+
+import * as os from 'os';
+import * as path from 'path';
+import { FileCacheStore } from './store.js';
+import { CacheConfig, CacheStats, CacheSource, CacheSetOptions, CacheResult } from './types.js';
+
+/**
+ * グローバルキャッシュ設定
+ */
+export interface GlobalCacheConfig extends Partial<CacheConfig> {
+  /** グローバルキャッシュの有効化 */
+  enabled: boolean;
+  /** プロジェクト固有キャッシュを優先するか */
+  preferProjectCache: boolean;
+  /** グローバルキャッシュのベースディレクトリ（デフォルト: ~/.shikigami） */
+  baseDir?: string;
+}
+
+/**
+ * デフォルトグローバルキャッシュ設定
+ */
+export const DEFAULT_GLOBAL_CACHE_CONFIG: GlobalCacheConfig = {
+  enabled: true,
+  preferProjectCache: true,
+  maxEntries: 5000,
+  defaultTtlSeconds: 3600 * 24 * 7, // 1週間
+  maxSizeBytes: 500 * 1024 * 1024, // 500MB
+};
+
+/**
+ * キャッシュスコープ
+ */
+export type CacheScope = 'global' | 'project';
+
+/**
+ * スコープ付きキャッシュ結果
+ */
+export interface ScopedCacheResult<T = unknown> extends CacheResult<T> {
+  /** キャッシュが見つかったスコープ */
+  scope?: CacheScope;
+}
+
+/**
+ * GlobalCacheStore
+ * ユーザー横断のグローバルキャッシュを管理
+ */
+export class GlobalCacheStore {
+  private globalStore: FileCacheStore;
+  private projectStore: FileCacheStore | null = null;
+  private config: GlobalCacheConfig;
+  private globalCacheDir: string;
+
+  constructor(config: Partial<GlobalCacheConfig> = {}) {
+    this.config = { ...DEFAULT_GLOBAL_CACHE_CONFIG, ...config };
+
+    // グローバルキャッシュディレクトリを設定
+    const baseDir = this.config.baseDir || path.join(os.homedir(), '.shikigami');
+    this.globalCacheDir = path.join(baseDir, 'global-cache');
+
+    // グローバルストアを初期化
+    this.globalStore = new FileCacheStore({
+      cacheDir: this.globalCacheDir,
+      maxEntries: this.config.maxEntries,
+      defaultTtlSeconds: this.config.defaultTtlSeconds,
+      maxSizeBytes: this.config.maxSizeBytes,
+    });
+  }
+
+  /**
+   * プロジェクト固有のキャッシュストアを設定
+   */
+  setProjectStore(projectCacheDir: string): void {
+    this.projectStore = new FileCacheStore({
+      cacheDir: projectCacheDir,
+      maxEntries: this.config.maxEntries,
+      defaultTtlSeconds: this.config.defaultTtlSeconds,
+      maxSizeBytes: this.config.maxSizeBytes,
+    });
+  }
+
+  /**
+   * プロジェクトストアをクリア
+   */
+  clearProjectStore(): void {
+    this.projectStore = null;
+  }
+
+  /**
+   * キャッシュエントリを取得（スコープ優先順位に従う）
+   */
+  async get<T = unknown>(key: string): Promise<ScopedCacheResult<T>> {
+    // プロジェクトキャッシュを優先する場合
+    if (this.config.preferProjectCache && this.projectStore) {
+      const projectResult = await this.projectStore.get<T>(key);
+      if (projectResult.hit) {
+        return { ...projectResult, scope: 'project' };
+      }
+    }
+
+    // グローバルキャッシュから取得
+    if (this.config.enabled) {
+      const globalResult = await this.globalStore.get<T>(key);
+      if (globalResult.hit) {
+        return { ...globalResult, scope: 'global' };
+      }
+    }
+
+    // プロジェクトキャッシュを後で確認（優先しない場合）
+    if (!this.config.preferProjectCache && this.projectStore) {
+      const projectResult = await this.projectStore.get<T>(key);
+      if (projectResult.hit) {
+        return { ...projectResult, scope: 'project' };
+      }
+    }
+
+    return { hit: false, key };
+  }
+
+  /**
+   * キャッシュエントリを保存
+   */
+  async set<T = unknown>(
+    key: string,
+    value: T,
+    options: CacheSetOptions & { scope?: CacheScope } = {}
+  ): Promise<void> {
+    const { scope = 'global', ...cacheOptions } = options;
+
+    if (scope === 'project' && this.projectStore) {
+      await this.projectStore.set(key, value, cacheOptions);
+    } else if (scope === 'global' && this.config.enabled) {
+      await this.globalStore.set(key, value, cacheOptions);
+    }
+  }
+
+  /**
+   * キャッシュエントリを削除
+   */
+  async delete(key: string, scope?: CacheScope): Promise<boolean> {
+    let deleted = false;
+
+    if (scope === 'project' || scope === undefined) {
+      if (this.projectStore) {
+        deleted = (await this.projectStore.delete(key)) || deleted;
+      }
+    }
+
+    if (scope === 'global' || scope === undefined) {
+      if (this.config.enabled) {
+        deleted = (await this.globalStore.delete(key)) || deleted;
+      }
+    }
+
+    return deleted;
+  }
+
+  /**
+   * キャッシュの存在確認
+   */
+  async has(key: string): Promise<{ exists: boolean; scope?: CacheScope }> {
+    if (this.config.preferProjectCache && this.projectStore) {
+      if (await this.projectStore.has(key)) {
+        return { exists: true, scope: 'project' };
+      }
+    }
+
+    if (this.config.enabled && (await this.globalStore.has(key))) {
+      return { exists: true, scope: 'global' };
+    }
+
+    if (!this.config.preferProjectCache && this.projectStore) {
+      if (await this.projectStore.has(key)) {
+        return { exists: true, scope: 'project' };
+      }
+    }
+
+    return { exists: false };
+  }
+
+  /**
+   * 全エントリを削除
+   */
+  async clear(scope?: CacheScope): Promise<void> {
+    if (scope === 'project' || scope === undefined) {
+      if (this.projectStore) {
+        await this.projectStore.clear();
+      }
+    }
+
+    if (scope === 'global' || scope === undefined) {
+      if (this.config.enabled) {
+        await this.globalStore.clear();
+      }
+    }
+  }
+
+  /**
+   * 統計情報を取得
+   */
+  async getStats(scope?: CacheScope): Promise<{
+    global?: CacheStats;
+    project?: CacheStats;
+    combined?: {
+      totalEntries: number;
+      totalSizeBytes: number;
+      globalHitRate: number;
+      projectHitRate: number;
+    };
+  }> {
+    const result: {
+      global?: CacheStats;
+      project?: CacheStats;
+      combined?: {
+        totalEntries: number;
+        totalSizeBytes: number;
+        globalHitRate: number;
+        projectHitRate: number;
+      };
+    } = {};
+
+    if (scope === 'global' || scope === undefined) {
+      if (this.config.enabled) {
+        result.global = await this.globalStore.getStats();
+      }
+    }
+
+    if (scope === 'project' || scope === undefined) {
+      if (this.projectStore) {
+        result.project = await this.projectStore.getStats();
+      }
+    }
+
+    // 結合統計
+    if (scope === undefined && result.global) {
+      result.combined = {
+        totalEntries: (result.global?.totalEntries || 0) + (result.project?.totalEntries || 0),
+        totalSizeBytes:
+          (result.global?.totalSizeBytes || 0) + (result.project?.totalSizeBytes || 0),
+        globalHitRate: result.global?.hitRate || 0,
+        projectHitRate: result.project?.hitRate || 0,
+      };
+    }
+
+    return result;
+  }
+
+  /**
+   * 期限切れエントリを削除
+   */
+  async evictExpired(scope?: CacheScope): Promise<{ global: number; project: number }> {
+    let globalEvicted = 0;
+    let projectEvicted = 0;
+
+    if (scope === 'global' || scope === undefined) {
+      if (this.config.enabled) {
+        globalEvicted = await this.globalStore.evictExpired();
+      }
+    }
+
+    if (scope === 'project' || scope === undefined) {
+      if (this.projectStore) {
+        projectEvicted = await this.projectStore.evictExpired();
+      }
+    }
+
+    return { global: globalEvicted, project: projectEvicted };
+  }
+
+  /**
+   * グローバルキャッシュディレクトリを取得
+   */
+  getGlobalCacheDir(): string {
+    return this.globalCacheDir;
+  }
+
+  /**
+   * 設定を取得
+   */
+  getConfig(): GlobalCacheConfig {
+    return { ...this.config };
+  }
+
+  /**
+   * グローバルキャッシュの有効/無効を切り替え
+   */
+  setEnabled(enabled: boolean): void {
+    this.config.enabled = enabled;
+  }
+
+  /**
+   * プロジェクトキャッシュ優先設定を変更
+   */
+  setPreferProjectCache(prefer: boolean): void {
+    this.config.preferProjectCache = prefer;
+  }
+
+  /**
+   * プロジェクトストアが設定されているか確認
+   */
+  hasProjectStore(): boolean {
+    return this.projectStore !== null;
+  }
+
+  /**
+   * 基盤となるストアを取得
+   */
+  getGlobalStore(): FileCacheStore {
+    return this.globalStore;
+  }
+
+  /**
+   * プロジェクトストアを取得
+   */
+  getProjectStore(): FileCacheStore | null {
+    return this.projectStore;
+  }
+}
+
+// シングルトンインスタンス
+let globalCacheInstance: GlobalCacheStore | null = null;
+
+/**
+ * デフォルトのグローバルキャッシュインスタンスを取得
+ */
+export function getGlobalCacheStore(config?: Partial<GlobalCacheConfig>): GlobalCacheStore {
+  if (!globalCacheInstance) {
+    globalCacheInstance = new GlobalCacheStore(config);
+  }
+  return globalCacheInstance;
+}
+
+/**
+ * グローバルキャッシュインスタンスをリセット（テスト用）
+ */
+export function resetGlobalCacheStore(): void {
+  globalCacheInstance = null;
+}
+
+/**
+ * グローバルキャッシュストアを作成
+ */
+export function createGlobalCacheStore(config?: Partial<GlobalCacheConfig>): GlobalCacheStore {
+  return new GlobalCacheStore(config);
+}

package/src/cache/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Cache Module Index
+ * v1.0.0 - REQ-CACHE-001
+ */
+
+export * from './types.js';
+export * from './store.js';
+export * from './manager.js';
+export * from './semantic.js';
+export * from './global.js';

package/src/cache/manager.ts

@@ -0,0 +1,325 @@
+/**
+ * Query Cache Manager
+ * v1.0.0 - REQ-CACHE-001-01
+ *
+ * 検索・訪問クエリのキャッシュ管理
+ */
+
+import { FileCacheStore, createCacheStore } from './store.js';
+import {
+  CacheConfig,
+  CacheResult,
+  CacheStats,
+  CacheSource,
+  CacheSetOptions,
+} from './types.js';
+
+/**
+ * 検索クエリのキャッシュキー生成パラメータ
+ */
+export interface SearchCacheKeyParams {
+  query: string;
+  engine?: string;
+  options?: Record<string, unknown>;
+}
+
+/**
+ * 訪問クエリのキャッシュキー生成パラメータ
+ */
+export interface VisitCacheKeyParams {
+  url: string;
+  options?: {
+    extractImages?: boolean;
+    extractLinks?: boolean;
+  };
+}
+
+/**
+ * 埋め込みキャッシュキー生成パラメータ
+ */
+export interface EmbeddingCacheKeyParams {
+  text: string;
+  model?: string;
+}
+
+/**
+ * キャッシュマネージャー設定
+ */
+export interface QueryCacheManagerConfig extends Partial<CacheConfig> {
+  /** 自動期限切れ削除の間隔 (秒) */
+  evictionIntervalSeconds?: number;
+  /** 統計保存の間隔 (秒) */
+  statsSaveIntervalSeconds?: number;
+}
+
+/**
+ * クエリキャッシュマネージャー
+ * 検索、訪問、埋め込みなどのクエリ結果をキャッシュ
+ */
+export class QueryCacheManager {
+  private store: FileCacheStore;
+  private config: QueryCacheManagerConfig;
+  private evictionTimer?: NodeJS.Timeout;
+  private statsSaveTimer?: NodeJS.Timeout;
+
+  constructor(config: QueryCacheManagerConfig = {}) {
+    this.config = {
+      evictionIntervalSeconds: 300, // 5分
+      statsSaveIntervalSeconds: 60, // 1分
+      ...config,
+    };
+    this.store = createCacheStore(config);
+  }
+
+  /**
+   * 定期的なメンテナンスタスクを開始
+   */
+  startMaintenanceTasks(): void {
+    // 期限切れ削除タイマー
+    if (this.config.evictionIntervalSeconds && this.config.evictionIntervalSeconds > 0) {
+      this.evictionTimer = setInterval(
+        () => this.store.evictExpired(),
+        this.config.evictionIntervalSeconds * 1000
+      );
+    }
+
+    // 統計保存タイマー
+    if (this.config.statsSaveIntervalSeconds && this.config.statsSaveIntervalSeconds > 0) {
+      this.statsSaveTimer = setInterval(
+        () => this.store.saveStats(),
+        this.config.statsSaveIntervalSeconds * 1000
+      );
+    }
+  }
+
+  /**
+   * メンテナンスタスクを停止
+   */
+  stopMaintenanceTasks(): void {
+    if (this.evictionTimer) {
+      clearInterval(this.evictionTimer);
+      this.evictionTimer = undefined;
+    }
+    if (this.statsSaveTimer) {
+      clearInterval(this.statsSaveTimer);
+      this.statsSaveTimer = undefined;
+    }
+  }
+
+  /**
+   * 検索クエリのキャッシュキーを生成
+   */
+  static generateSearchKey(params: SearchCacheKeyParams): string {
+    const { query, engine = 'default', options = {} } = params;
+    const optionsStr = Object.keys(options).length > 0 ? JSON.stringify(options) : '';
+    return `search:${engine}:${query}${optionsStr ? ':' + optionsStr : ''}`;
+  }
+
+  /**
+   * 訪問クエリのキャッシュキーを生成
+   */
+  static generateVisitKey(params: VisitCacheKeyParams): string {
+    const { url, options = {} } = params;
+    const optionsStr = Object.keys(options).length > 0 ? JSON.stringify(options) : '';
+    return `visit:${url}${optionsStr ? ':' + optionsStr : ''}`;
+  }
+
+  /**
+   * 埋め込みキャッシュキーを生成
+   */
+  static generateEmbeddingKey(params: EmbeddingCacheKeyParams): string {
+    const { text, model = 'default' } = params;
+    // テキストが長い場合はハッシュ化
+    const textKey = text.length > 100 ? FileCacheStore.generateQueryHash(text) : text;
+    return `embedding:${model}:${textKey}`;
+  }
+
+  /**
+   * 検索結果をキャッシュから取得
+   */
+  async getSearchResult<T = unknown>(params: SearchCacheKeyParams): Promise<CacheResult<T>> {
+    const key = QueryCacheManager.generateSearchKey(params);
+    return this.store.get<T>(key);
+  }
+
+  /**
+   * 検索結果をキャッシュに保存
+   */
+  async setSearchResult<T = unknown>(
+    params: SearchCacheKeyParams,
+    value: T,
+    options: Omit<CacheSetOptions, 'source'> = {}
+  ): Promise<void> {
+    const key = QueryCacheManager.generateSearchKey(params);
+    await this.store.set(key, value, { ...options, source: 'search' });
+  }
+
+  /**
+   * 訪問結果をキャッシュから取得
+   */
+  async getVisitResult<T = unknown>(params: VisitCacheKeyParams): Promise<CacheResult<T>> {
+    const key = QueryCacheManager.generateVisitKey(params);
+    return this.store.get<T>(key);
+  }
+
+  /**
+   * 訪問結果をキャッシュに保存
+   */
+  async setVisitResult<T = unknown>(
+    params: VisitCacheKeyParams,
+    value: T,
+    options: Omit<CacheSetOptions, 'source'> = {}
+  ): Promise<void> {
+    const key = QueryCacheManager.generateVisitKey(params);
+    await this.store.set(key, value, { ...options, source: 'visit' });
+  }
+
+  /**
+   * 埋め込みベクトルをキャッシュから取得
+   */
+  async getEmbedding<T = unknown>(params: EmbeddingCacheKeyParams): Promise<CacheResult<T>> {
+    const key = QueryCacheManager.generateEmbeddingKey(params);
+    return this.store.get<T>(key);
+  }
+
+  /**
+   * 埋め込みベクトルをキャッシュに保存
+   */
+  async setEmbedding<T = unknown>(
+    params: EmbeddingCacheKeyParams,
+    value: T,
+    options: Omit<CacheSetOptions, 'source'> = {}
+  ): Promise<void> {
+    const key = QueryCacheManager.generateEmbeddingKey(params);
+    await this.store.set(key, value, { ...options, source: 'embedding' });
+  }
+
+  /**
+   * 汎用的なキャッシュ取得
+   */
+  async get<T = unknown>(key: string): Promise<CacheResult<T>> {
+    return this.store.get<T>(key);
+  }
+
+  /**
+   * 汎用的なキャッシュ保存
+   */
+  async set<T = unknown>(key: string, value: T, options: CacheSetOptions = {}): Promise<void> {
+    await this.store.set(key, value, options);
+  }
+
+  /**
+   * キャッシュエントリを削除
+   */
+  async delete(key: string): Promise<boolean> {
+    return this.store.delete(key);
+  }
+
+  /**
+   * URLに関連するキャッシュを削除
+   */
+  async invalidateUrl(url: string): Promise<number> {
+    let deletedCount = 0;
+
+    // 訪問キャッシュを削除
+    const visitKey = QueryCacheManager.generateVisitKey({ url });
+    if (await this.store.delete(visitKey)) {
+      deletedCount++;
+    }
+
+    // URL関連の検索キャッシュを検索・削除
+    const entries = await this.store.query({ source: 'visit' });
+    for (const entry of entries) {
+      if (entry.key.includes(url)) {
+        await this.store.delete(entry.key);
+        deletedCount++;
+      }
+    }
+
+    return deletedCount;
+  }
+
+  /**
+   * 特定のソースのキャッシュをすべて削除
+   */
+  async invalidateBySource(source: CacheSource): Promise<number> {
+    const entries = await this.store.query({ source });
+    let deletedCount = 0;
+
+    for (const entry of entries) {
+      if (await this.store.delete(entry.key)) {
+        deletedCount++;
+      }
+    }
+
+    return deletedCount;
+  }
+
+  /**
+   * すべてのキャッシュをクリア
+   */
+  async clear(): Promise<void> {
+    await this.store.clear();
+  }
+
+  /**
+   * 統計情報を取得
+   */
+  async getStats(): Promise<CacheStats> {
+    return this.store.getStats();
+  }
+
+  /**
+   * 期限切れエントリを削除
+   */
+  async evictExpired(): Promise<number> {
+    return this.store.evictExpired();
+  }
+
+  /**
+   * キャッシュサマリーを取得（ログ用）
+   */
+  async getSummary(): Promise<string> {
+    const stats = await this.getStats();
+    const hitRatePercent = (stats.hitRate * 100).toFixed(1);
+    const sizeMB = (stats.totalSizeBytes / (1024 * 1024)).toFixed(2);
+
+    return [
+      `Cache Summary:`,
+      `  Entries: ${stats.totalEntries}`,
+      `  Size: ${sizeMB} MB`,
+      `  Hit Rate: ${hitRatePercent}%`,
+      `  Hits: ${stats.hits}, Misses: ${stats.misses}`,
+      `  Evictions: ${stats.expiredEvictions} (expired), ${stats.lruEvictions} (LRU)`,
+    ].join('\n');
+  }
+
+  /**
+   * ストアインスタンスを取得（テスト用）
+   */
+  getStore(): FileCacheStore {
+    return this.store;
+  }
+}
+
+/**
+ * シングルトンインスタンス
+ */
+let defaultManager: QueryCacheManager | null = null;
+
+/**
+ * デフォルトのキャッシュマネージャーを取得
+ */
+export function getDefaultCacheManager(config?: QueryCacheManagerConfig): QueryCacheManager {
+  if (!defaultManager) {
+    defaultManager = new QueryCacheManager(config);
+  }
+  return defaultManager;
+}
+
+/**
+ * キャッシュマネージャーを作成
+ */
+export function createCacheManager(config?: QueryCacheManagerConfig): QueryCacheManager {
+  return new QueryCacheManager(config);
+}