gitmem-mcp 0.2.0

package/dist/services/cache.js

@@ -0,0 +1,384 @@
+/**
+ * GitMem Cache Service
+ *
+ * File-based cache for GitMem MCP operations.
+ * Caches search results to avoid repeated ww-mcp calls.
+ *
+ * Design: docs/systems/gitmem-caching.md
+ * Issue: OD-473
+ */
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync, statSync } from "fs";
+import { join } from "path";
+// Default cache directory
+// Uses env var if set, otherwise falls back to user's home directory or /tmp
+const DEFAULT_CACHE_DIR = process.env.GITMEM_CACHE_DIR ||
+    (process.env.HOME ? `${process.env.HOME}/.cache/gitmem` : "/tmp/gitmem-cache");
+// TTL values in milliseconds
+const TTL = {
+    SCAR_SEARCH: 15 * 60 * 1000, // 15 minutes
+    DECISIONS: 5 * 60 * 1000, // 5 minutes
+    WINS: 5 * 60 * 1000, // 5 minutes
+    SESSIONS: 10 * 60 * 1000, // 10 minutes (sessions change slowly)
+    SCAR_USAGE: 10 * 60 * 1000, // 10 minutes
+};
+// Max cache sizes
+const MAX_RESULT_CACHE_SIZE = 10 * 1024 * 1024; // 10MB
+/**
+ * Generate a short hash for cache keys
+ */
+function hashText(text) {
+    return createHash("sha256")
+        .update(text.toLowerCase().trim())
+        .digest("hex")
+        .slice(0, 16);
+}
+/**
+ * CacheService class
+ *
+ * Provides file-based caching for GitMem operations.
+ * Designed for graceful degradation - cache failures never block operations.
+ */
+export class CacheService {
+    cacheDir;
+    resultsDir;
+    enabled = true;
+    // Stats tracking
+    hits = 0;
+    misses = 0;
+    constructor(cacheDir = DEFAULT_CACHE_DIR) {
+        this.cacheDir = cacheDir;
+        this.resultsDir = join(cacheDir, "results");
+        this.init();
+    }
+    /**
+     * Initialize cache directories
+     */
+    init() {
+        try {
+            if (!existsSync(this.cacheDir)) {
+                mkdirSync(this.cacheDir, { recursive: true, mode: 0o700 });
+            }
+            if (!existsSync(this.resultsDir)) {
+                mkdirSync(this.resultsDir, { recursive: true, mode: 0o700 });
+            }
+        }
+        catch (error) {
+            console.warn("[cache] Failed to initialize cache directory:", error);
+            this.enabled = false;
+        }
+    }
+    /**
+     * Check if cache is enabled and working
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Disable cache (for testing or on errors)
+     */
+    disable() {
+        this.enabled = false;
+    }
+    /**
+     * Generate cache key for scar search
+     */
+    scarSearchKey(query, project, matchCount) {
+        return `scar_search:${hashText(query)}:${project}:${matchCount}`;
+    }
+    /**
+     * Generate cache key for decisions
+     */
+    decisionsKey(project, limit) {
+        return `decisions:${project}:${limit}`;
+    }
+    /**
+     * Generate cache key for wins
+     */
+    winsKey(project, limit) {
+        return `wins:${project}:${limit}`;
+    }
+    /**
+     * Get cached result
+     */
+    async getResult(key) {
+        if (!this.enabled)
+            return null;
+        try {
+            const filename = this.keyToFilename(key);
+            const filepath = join(this.resultsDir, filename);
+            if (!existsSync(filepath)) {
+                this.misses++;
+                return null;
+            }
+            const content = readFileSync(filepath, "utf-8");
+            const entry = JSON.parse(content);
+            // Check expiration
+            const now = Date.now();
+            if (now > entry.expires_at) {
+                // Expired - delete and return null
+                try {
+                    unlinkSync(filepath);
+                }
+                catch {
+                    // Ignore delete errors
+                }
+                this.misses++;
+                console.error(`[cache] EXPIRED: ${key}`);
+                return null;
+            }
+            this.hits++;
+            const age_ms = now - entry.created_at;
+            console.error(`[cache] HIT: ${key} (age: ${age_ms}ms)`);
+            return { data: entry.data, age_ms };
+        }
+        catch (error) {
+            console.warn(`[cache] Error reading ${key}:`, error);
+            this.misses++;
+            return null;
+        }
+    }
+    /**
+     * Set cached result
+     */
+    async setResult(key, data, ttlMs) {
+        if (!this.enabled)
+            return;
+        try {
+            const now = Date.now();
+            const entry = {
+                key,
+                created_at: now,
+                expires_at: now + ttlMs,
+                data,
+            };
+            const filename = this.keyToFilename(key);
+            const filepath = join(this.resultsDir, filename);
+            const content = JSON.stringify(entry, null, 2);
+            writeFileSync(filepath, content, { mode: 0o600 });
+            console.error(`[cache] SET: ${key} (TTL: ${ttlMs}ms)`);
+        }
+        catch (error) {
+            console.warn(`[cache] Error writing ${key}:`, error);
+            // Don't disable cache on write errors - might be transient
+        }
+    }
+    /**
+     * Convenience method: get or fetch scar search results
+     */
+    async getOrFetchScarSearch(query, project, matchCount, fetcher) {
+        const key = this.scarSearchKey(query, project, matchCount);
+        const cached = await this.getResult(key);
+        if (cached) {
+            return { data: cached.data, cache_hit: true, cache_age_ms: cached.age_ms };
+        }
+        // Cache miss - fetch from source
+        const data = await fetcher();
+        // Cache the result (async, don't await)
+        this.setResult(key, data, TTL.SCAR_SEARCH).catch(() => { });
+        return { data, cache_hit: false };
+    }
+    /**
+     * Convenience method: get or fetch decisions
+     */
+    async getOrFetchDecisions(project, limit, fetcher) {
+        const key = this.decisionsKey(project, limit);
+        const cached = await this.getResult(key);
+        if (cached) {
+            return { data: cached.data, cache_hit: true, cache_age_ms: cached.age_ms };
+        }
+        // Cache miss - fetch from source
+        const data = await fetcher();
+        // Cache the result (async, don't await)
+        this.setResult(key, data, TTL.DECISIONS).catch(() => { });
+        return { data, cache_hit: false };
+    }
+    /**
+     * Convenience method: get or fetch wins
+     */
+    async getOrFetchWins(project, limit, fetcher) {
+        const key = this.winsKey(project, limit);
+        const cached = await this.getResult(key);
+        if (cached) {
+            return { data: cached.data, cache_hit: true, cache_age_ms: cached.age_ms };
+        }
+        // Cache miss - fetch from source
+        const data = await fetcher();
+        // Cache the result (async, don't await)
+        this.setResult(key, data, TTL.WINS).catch(() => { });
+        return { data, cache_hit: false };
+    }
+    /**
+     * Generate cache key for sessions (analytics)
+     */
+    sessionsKey(project, days, agent) {
+        return `sessions:${project}:${days}d${agent ? `:${agent}` : ""}`;
+    }
+    /**
+     * Generate cache key for scar usage (analytics)
+     */
+    scarUsageKey(project, days, agent) {
+        return `scar_usage:${project}:${days}d${agent ? `:${agent}` : ""}`;
+    }
+    /**
+     * Convenience method: get or fetch sessions
+     */
+    async getOrFetchSessions(project, days, agent, fetcher) {
+        const key = this.sessionsKey(project, days, agent);
+        const cached = await this.getResult(key);
+        if (cached) {
+            return { data: cached.data, cache_hit: true, cache_age_ms: cached.age_ms };
+        }
+        const data = await fetcher();
+        this.setResult(key, data, TTL.SESSIONS).catch(() => { });
+        return { data, cache_hit: false };
+    }
+    /**
+     * Convenience method: get or fetch scar usage
+     */
+    async getOrFetchScarUsage(project, days, agent, fetcher) {
+        const key = this.scarUsageKey(project, days, agent);
+        const cached = await this.getResult(key);
+        if (cached) {
+            return { data: cached.data, cache_hit: true, cache_age_ms: cached.age_ms };
+        }
+        const data = await fetcher();
+        this.setResult(key, data, TTL.SCAR_USAGE).catch(() => { });
+        return { data, cache_hit: false };
+    }
+    /**
+     * Clean up expired entries
+     */
+    async cleanup() {
+        if (!this.enabled)
+            return 0;
+        let cleaned = 0;
+        try {
+            const files = readdirSync(this.resultsDir);
+            const now = Date.now();
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                const filepath = join(this.resultsDir, file);
+                try {
+                    const content = readFileSync(filepath, "utf-8");
+                    const entry = JSON.parse(content);
+                    if (now > entry.expires_at) {
+                        unlinkSync(filepath);
+                        cleaned++;
+                    }
+                }
+                catch {
+                    // Delete corrupted files
+                    try {
+                        unlinkSync(filepath);
+                        cleaned++;
+                    }
+                    catch {
+                        // Ignore
+                    }
+                }
+            }
+            if (cleaned > 0) {
+                console.error(`[cache] Cleaned up ${cleaned} expired entries`);
+            }
+        }
+        catch (error) {
+            console.warn("[cache] Error during cleanup:", error);
+        }
+        return cleaned;
+    }
+    /**
+     * Clear all cached data
+     */
+    async clear() {
+        try {
+            const files = readdirSync(this.resultsDir);
+            for (const file of files) {
+                try {
+                    unlinkSync(join(this.resultsDir, file));
+                }
+                catch {
+                    // Ignore individual file errors
+                }
+            }
+            console.error("[cache] Cache cleared");
+        }
+        catch (error) {
+            console.warn("[cache] Error clearing cache:", error);
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    async getStats() {
+        const stats = {
+            resultCount: 0,
+            resultBytes: 0,
+            oldestEntry: null,
+        };
+        if (!this.enabled)
+            return stats;
+        try {
+            const files = readdirSync(this.resultsDir);
+            let oldestTime = Infinity;
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                const filepath = join(this.resultsDir, file);
+                try {
+                    const fileStat = statSync(filepath);
+                    stats.resultCount++;
+                    stats.resultBytes += fileStat.size;
+                    const content = readFileSync(filepath, "utf-8");
+                    const entry = JSON.parse(content);
+                    if (entry.created_at < oldestTime) {
+                        oldestTime = entry.created_at;
+                    }
+                }
+                catch {
+                    // Skip problematic files
+                }
+            }
+            if (oldestTime !== Infinity) {
+                stats.oldestEntry = new Date(oldestTime);
+            }
+            // Calculate hit rate
+            const total = this.hits + this.misses;
+            if (total > 0) {
+                stats.hitRate = this.hits / total;
+            }
+        }
+        catch (error) {
+            console.warn("[cache] Error getting stats:", error);
+        }
+        return stats;
+    }
+    /**
+     * Convert cache key to safe filename
+     */
+    keyToFilename(key) {
+        // Replace unsafe chars with underscores, keep it readable
+        return key.replace(/[^a-zA-Z0-9_:-]/g, "_") + ".json";
+    }
+}
+// Singleton instance
+let cacheInstance = null;
+/**
+ * Get the cache service singleton
+ */
+export function getCache() {
+    if (!cacheInstance) {
+        cacheInstance = new CacheService();
+    }
+    return cacheInstance;
+}
+/**
+ * Reset cache instance (for testing)
+ */
+export function resetCache() {
+    cacheInstance = null;
+}
+// Export TTL values for external use
+export { TTL };
+//# sourceMappingURL=cache.js.map

package/dist/services/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/services/cache.ts"],"names":[],"mappings":"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"}

package/dist/services/cache.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CacheService Unit Tests
+ *
+ * Tests for the GitMem file-based caching layer.
+ * Issue: OD-473
+ */
+export {};
+//# sourceMappingURL=cache.test.d.ts.map

package/dist/services/cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.test.d.ts","sourceRoot":"","sources":["../../src/services/cache.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/services/cache.test.js

@@ -0,0 +1,267 @@
+/**
+ * CacheService Unit Tests
+ *
+ * Tests for the GitMem file-based caching layer.
+ * Issue: OD-473
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { existsSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { CacheService, TTL, getCache, resetCache } from "./cache.js";
+// Test cache directory (isolated from production)
+const TEST_CACHE_DIR = "/tmp/gitmem-cache-test";
+describe("CacheService", () => {
+    let cache;
+    beforeEach(() => {
+        // Clean up any existing test cache
+        if (existsSync(TEST_CACHE_DIR)) {
+            rmSync(TEST_CACHE_DIR, { recursive: true });
+        }
+        cache = new CacheService(TEST_CACHE_DIR);
+    });
+    afterEach(() => {
+        // Clean up test cache
+        if (existsSync(TEST_CACHE_DIR)) {
+            rmSync(TEST_CACHE_DIR, { recursive: true });
+        }
+        resetCache();
+    });
+    describe("initialization", () => {
+        it("creates cache directory on initialization", () => {
+            expect(existsSync(TEST_CACHE_DIR)).toBe(true);
+            expect(existsSync(join(TEST_CACHE_DIR, "results"))).toBe(true);
+        });
+        it("is enabled after successful initialization", () => {
+            expect(cache.isEnabled()).toBe(true);
+        });
+        it("can be disabled", () => {
+            cache.disable();
+            expect(cache.isEnabled()).toBe(false);
+        });
+    });
+    describe("cache key generation", () => {
+        it("generates consistent scar search keys", () => {
+            const key1 = cache.scarSearchKey("test query", "orchestra_dev", 5);
+            const key2 = cache.scarSearchKey("test query", "orchestra_dev", 5);
+            expect(key1).toBe(key2);
+        });
+        it("generates different keys for different queries", () => {
+            const key1 = cache.scarSearchKey("query one", "orchestra_dev", 5);
+            const key2 = cache.scarSearchKey("query two", "orchestra_dev", 5);
+            expect(key1).not.toBe(key2);
+        });
+        it("generates different keys for different projects", () => {
+            const key1 = cache.scarSearchKey("test", "orchestra_dev", 5);
+            const key2 = cache.scarSearchKey("test", "weekend_warrior", 5);
+            expect(key1).not.toBe(key2);
+        });
+        it("generates different keys for different match counts", () => {
+            const key1 = cache.scarSearchKey("test", "orchestra_dev", 3);
+            const key2 = cache.scarSearchKey("test", "orchestra_dev", 5);
+            expect(key1).not.toBe(key2);
+        });
+        it("normalizes query text (lowercase, trim)", () => {
+            const key1 = cache.scarSearchKey("  Test Query  ", "orchestra_dev", 5);
+            const key2 = cache.scarSearchKey("test query", "orchestra_dev", 5);
+            expect(key1).toBe(key2);
+        });
+        it("generates decisions keys", () => {
+            const key = cache.decisionsKey("orchestra_dev", 5);
+            expect(key).toBe("decisions:orchestra_dev:5");
+        });
+    });
+    describe("setResult and getResult", () => {
+        it("stores and retrieves data", async () => {
+            const testData = { items: [1, 2, 3], message: "test" };
+            await cache.setResult("test-key", testData, 60000);
+            const result = await cache.getResult("test-key");
+            expect(result).not.toBeNull();
+            expect(result.data).toEqual(testData);
+        });
+        it("returns null for non-existent key", async () => {
+            const result = await cache.getResult("non-existent");
+            expect(result).toBeNull();
+        });
+        it("returns cache age in milliseconds", async () => {
+            const testData = { test: true };
+            await cache.setResult("test-key", testData, 60000);
+            // Wait a small amount
+            await new Promise((r) => setTimeout(r, 10));
+            const result = await cache.getResult("test-key");
+            expect(result).not.toBeNull();
+            expect(result.age_ms).toBeGreaterThan(0);
+            expect(result.age_ms).toBeLessThan(1000); // Should be very fast
+        });
+        it("returns null for expired entries", async () => {
+            const testData = { test: true };
+            // Set with very short TTL
+            await cache.setResult("expiring-key", testData, 1);
+            // Wait for expiration
+            await new Promise((r) => setTimeout(r, 10));
+            const result = await cache.getResult("expiring-key");
+            expect(result).toBeNull();
+        });
+        it("returns null when cache is disabled", async () => {
+            cache.disable();
+            await cache.setResult("test-key", { test: true }, 60000);
+            const result = await cache.getResult("test-key");
+            expect(result).toBeNull();
+        });
+    });
+    describe("getOrFetchScarSearch", () => {
+        it("returns cached data on hit", async () => {
+            const mockData = [{ id: "1", title: "Scar 1" }];
+            let fetchCount = 0;
+            const fetcher = async () => {
+                fetchCount++;
+                return mockData;
+            };
+            // First call - should fetch
+            const result1 = await cache.getOrFetchScarSearch("test query", "orchestra_dev", 5, fetcher);
+            expect(result1.cache_hit).toBe(false);
+            expect(result1.data).toEqual(mockData);
+            expect(fetchCount).toBe(1);
+            // Second call - should use cache
+            const result2 = await cache.getOrFetchScarSearch("test query", "orchestra_dev", 5, fetcher);
+            expect(result2.cache_hit).toBe(true);
+            expect(result2.data).toEqual(mockData);
+            expect(result2.cache_age_ms).toBeDefined();
+            expect(fetchCount).toBe(1); // Fetcher not called again
+        });
+        it("fetches on cache miss", async () => {
+            const mockData = [{ id: "1", title: "Scar 1" }];
+            const fetcher = async () => mockData;
+            const result = await cache.getOrFetchScarSearch("new query", "orchestra_dev", 5, fetcher);
+            expect(result.cache_hit).toBe(false);
+            expect(result.data).toEqual(mockData);
+        });
+    });
+    describe("getOrFetchDecisions", () => {
+        it("returns cached data on hit", async () => {
+            const mockData = [{ id: "1", title: "Decision 1" }];
+            let fetchCount = 0;
+            const fetcher = async () => {
+                fetchCount++;
+                return mockData;
+            };
+            // First call - should fetch
+            const result1 = await cache.getOrFetchDecisions("orchestra_dev", 5, fetcher);
+            expect(result1.cache_hit).toBe(false);
+            expect(fetchCount).toBe(1);
+            // Second call - should use cache
+            const result2 = await cache.getOrFetchDecisions("orchestra_dev", 5, fetcher);
+            expect(result2.cache_hit).toBe(true);
+            expect(fetchCount).toBe(1);
+        });
+    });
+    describe("cleanup", () => {
+        it("removes expired entries", async () => {
+            // Create an expired entry manually
+            const expiredEntry = {
+                key: "expired-key",
+                created_at: Date.now() - 100000,
+                expires_at: Date.now() - 50000, // Expired
+                data: { test: true },
+            };
+            const filepath = join(TEST_CACHE_DIR, "results", "expired-key.json");
+            writeFileSync(filepath, JSON.stringify(expiredEntry));
+            // Create a valid entry
+            await cache.setResult("valid-key", { test: true }, 60000);
+            // Run cleanup
+            const cleaned = await cache.cleanup();
+            expect(cleaned).toBe(1);
+            // Verify expired entry is gone
+            expect(existsSync(filepath)).toBe(false);
+            // Verify valid entry remains
+            const validResult = await cache.getResult("valid-key");
+            expect(validResult).not.toBeNull();
+        });
+    });
+    describe("clear", () => {
+        it("removes all cached entries", async () => {
+            await cache.setResult("key1", { test: 1 }, 60000);
+            await cache.setResult("key2", { test: 2 }, 60000);
+            await cache.clear();
+            const result1 = await cache.getResult("key1");
+            const result2 = await cache.getResult("key2");
+            expect(result1).toBeNull();
+            expect(result2).toBeNull();
+        });
+    });
+    describe("getStats", () => {
+        it("returns cache statistics", async () => {
+            await cache.setResult("key1", { test: 1 }, 60000);
+            await cache.setResult("key2", { test: 2 }, 60000);
+            const stats = await cache.getStats();
+            expect(stats.resultCount).toBe(2);
+            expect(stats.resultBytes).toBeGreaterThan(0);
+            expect(stats.oldestEntry).toBeInstanceOf(Date);
+        });
+        it("tracks hit rate", async () => {
+            await cache.setResult("key1", { test: 1 }, 60000);
+            // Generate some hits and misses
+            await cache.getResult("key1"); // Hit
+            await cache.getResult("key1"); // Hit
+            await cache.getResult("nonexistent"); // Miss
+            const stats = await cache.getStats();
+            expect(stats.hitRate).toBeCloseTo(2 / 3, 1);
+        });
+    });
+    describe("TTL values", () => {
+        it("exports correct TTL values", () => {
+            expect(TTL.SCAR_SEARCH).toBe(15 * 60 * 1000); // 15 minutes
+            expect(TTL.DECISIONS).toBe(5 * 60 * 1000); // 5 minutes
+        });
+    });
+    describe("singleton pattern", () => {
+        it("getCache returns same instance", () => {
+            // Note: getCache uses default dir which may not be writable in test env
+            // This test verifies the singleton behavior, not the cache functionality
+            resetCache();
+            // Set env var to use test directory
+            const originalDir = process.env.GITMEM_CACHE_DIR;
+            process.env.GITMEM_CACHE_DIR = TEST_CACHE_DIR;
+            try {
+                const cache1 = getCache();
+                const cache2 = getCache();
+                expect(cache1).toBe(cache2);
+            }
+            finally {
+                process.env.GITMEM_CACHE_DIR = originalDir;
+                resetCache();
+            }
+        });
+        it("resetCache creates new instance", () => {
+            const originalDir = process.env.GITMEM_CACHE_DIR;
+            process.env.GITMEM_CACHE_DIR = TEST_CACHE_DIR;
+            try {
+                const cache1 = getCache();
+                resetCache();
+                const cache2 = getCache();
+                expect(cache1).not.toBe(cache2);
+            }
+            finally {
+                process.env.GITMEM_CACHE_DIR = originalDir;
+                resetCache();
+            }
+        });
+    });
+    describe("error handling", () => {
+        it("gracefully handles corrupted cache files", async () => {
+            // Write corrupted JSON
+            const filepath = join(TEST_CACHE_DIR, "results", "corrupted.json");
+            writeFileSync(filepath, "not valid json {{{");
+            // Should return null, not throw
+            const result = await cache.getResult("corrupted");
+            expect(result).toBeNull();
+        });
+        it("gracefully handles file system errors", async () => {
+            // Disable cache to simulate error condition
+            cache.disable();
+            // Operations should not throw
+            await expect(cache.setResult("key", { test: true }, 60000)).resolves.not.toThrow();
+            await expect(cache.getResult("key")).resolves.toBeNull();
+        });
+    });
+});
+//# sourceMappingURL=cache.test.js.map