@cachly-dev/mcp-server 0.10.61 → 0.10.64

package/dist/src/utils.js

@@ -10,4 +10,80 @@ export function safeJsonParse(raw, fallback) {
         return fallback;
     }
 }
+/**
+ * Runs a promise with a hard timeout. If it doesn't settle within `ms`, resolves
+ * with `fallback` instead of hanging. A memory tool must NEVER block the agent's
+ * turn — a slow Redis scan or unreachable backend degrades gracefully to a fallback.
+ */
+export async function withTimeout(p, ms, fallback) {
+    let timer;
+    const guard = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(fallback), ms);
+    });
+    try {
+        return await Promise.race([p, guard]);
+    }
+    catch {
+        return fallback;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Collects keys matching a pattern with a hard cap and timeout. Prevents a tool
+ * from hanging on a huge keyspace: stops early at `max` keys, and resolves with
+ * whatever was gathered if the scan exceeds `timeoutMs`. Never rejects.
+ */
+export function scanKeys(redis, pattern, opts = {}) {
+    const max = opts.max ?? 1000;
+    const timeoutMs = opts.timeoutMs ?? 3000;
+    return new Promise((resolve) => {
+        const keys = [];
+        let done = false;
+        const finish = () => { if (!done) {
+            done = true;
+            resolve(keys);
+        } };
+        const timer = setTimeout(finish, timeoutMs);
+        try {
+            const stream = redis.scanStream({ match: pattern, count: opts.count ?? 200 });
+            stream.on('data', (batch) => {
+                for (const k of batch) {
+                    keys.push(k);
+                    if (keys.length >= max) {
+                        clearTimeout(timer);
+                        finish();
+                        return;
+                    }
+                }
+            });
+            stream.on('end', () => { clearTimeout(timer); finish(); });
+            stream.on('error', () => { clearTimeout(timer); finish(); });
+        }
+        catch {
+            clearTimeout(timer);
+            finish();
+        }
+    });
+}
+/**
+ * Normalizes a git path that may come from `--name-only` with rename notation,
+ * e.g. `src/{old => new}/file.ts` → `src/new/file.ts`, and `a => b` → `b`.
+ * Returns the post-rename path so file nodes don't fragment on renames.
+ */
+export function normalizeGitPath(raw) {
+    let p = raw.trim();
+    if (!p)
+        return p;
+    // Brace rename: dir/{old => new}/file  →  dir/new/file
+    p = p.replace(/\{[^}]*=>\s*([^}]*)\}/g, (_m, after) => after.trim());
+    // Bare rename: old => new  →  new
+    const arrow = p.split('=>');
+    if (arrow.length === 2)
+        p = arrow[1].trim();
+    // Collapse any double slashes introduced by an empty rename segment.
+    return p.replace(/\/{2,}/g, '/').replace(/^\/|\/$/g, '');
+}
 //# sourceMappingURL=utils.js.map

package/dist/src/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAI,GAA8B,EAAE,QAAW;IAC1E,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.10.61",
+  "version": "0.10.64",
   "mcpName": "io.github.cachly-dev/cachly-mcp",
-  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. Persistent memory + causal root-cause analysis for Claude Code, Cursor, Copilot & Windsurf. Learns from every bug fix, git commit, and CI run automatically. Arrives pre-briefed. Predicts failures before they happen. 100 MCP tools · Free tier forever · GDPR · EU servers.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. Persistent memory + causal root-cause analysis for Claude Code, Cursor, Copilot & Windsurf. Learns from every bug fix, git commit, and CI run automatically. Arrives pre-briefed. Predicts failures before they happen. 101 MCP tools · Free tier forever · GDPR · EU servers.",
   "type": "module",
   "bin": {
     "cachly-mcp": "dist/src/index.js"

package/server.json

@@ -1,18 +1,18 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.cachly-dev/cachly-mcp",
-  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 100 MCP tools · Free tier · EU servers · GDPR.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 101 MCP tools · Free tier · EU servers · GDPR.",
   "repository": {
     "url": "https://github.com/cachly-dev/cachly-mcp",
     "source": "github"
   },
-  "version": "0.10.61",
+  "version": "0.10.64",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.10.61",
+      "version": "0.10.64",
       "transport": {
         "type": "stdio"
       }

package/src/__tests__/brain-flow.test.ts

@@ -33,11 +33,19 @@ class MockRedis {
     return this.store.get(key) ?? null;
   }
 
-  async set(key: string, value: string): Promise<'OK'> {
+  async set(key: string, value: string, ...opts: unknown[]): Promise<'OK' | null> {
+    // Honor a trailing 'NX' flag so first-wins semantics (born_at, first_recall_at) work.
+    if (opts.includes('NX') && this.store.has(key)) return null;
     this.store.set(key, value);
     return 'OK';
   }
 
+  async incr(key: string): Promise<number> {
+    const next = parseInt(this.store.get(key) ?? '0', 10) + 1;
+    this.store.set(key, String(next));
+    return next;
+  }
+
   async rpush(key: string, ...values: string[]): Promise<number> {
     const list = this.lists.get(key) ?? [];
     list.push(...values);
@@ -1352,3 +1360,113 @@ describe('Phase 3C: brain_coverage', () => {
     expect(scoreAfter).toBeGreaterThan(scoreBefore);
   });
 });
+
+describe('Phase 3 stability: input guards', () => {
+  let redis: MockRedis;
+  const iid = 'i1';
+  const getConn = async () => redis as unknown as Redis;
+
+  beforeEach(() => { redis = new MockRedis(); });
+
+  it('brain_who_knows rejects empty topic without crashing', async () => {
+    const out = await handleBrainTool('brain_who_knows', { instance_id: iid, topic: '' }, getConn, noopApiFetch);
+    expect(out).toContain('requires a non-empty');
+  });
+
+  it('brain_who_knows rejects undefined topic without crashing', async () => {
+    const out = await handleBrainTool('brain_who_knows', { instance_id: iid }, getConn, noopApiFetch);
+    expect(out).toContain('requires a non-empty');
+  });
+
+  it('brain_who_knows clamps an absurd limit', async () => {
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:x', outcome: 'success',
+      what_worked: 'patch', author: 'alice',
+    }, getConn, noopApiFetch);
+    const out = await handleBrainTool('brain_who_knows', { instance_id: iid, topic: 'fix', limit: 99999 }, getConn, noopApiFetch);
+    expect(out).toContain('alice');
+  });
+
+  it('brain_file_map filters out empty path strings', async () => {
+    const out = await handleBrainTool('brain_file_map', { instance_id: iid, file_paths: ['', '  ', ''] }, getConn, noopApiFetch);
+    expect(out).toContain('Pass at least one file path');
+  });
+
+  it('brain_file_map handles non-array file_paths gracefully', async () => {
+    const out = await handleBrainTool('brain_file_map', { instance_id: iid, file_paths: 'not-an-array' as unknown as string[] }, getConn, noopApiFetch);
+    expect(out).toContain('Pass at least one file path');
+  });
+});
+
+describe('Phase 3C: brain_metrics — the three decisive metrics', () => {
+  let redis: MockRedis;
+  const iid = 'i1';
+  const getConn = async () => redis as unknown as Redis;
+
+  beforeEach(() => { redis = new MockRedis(); });
+
+  it('reports "not enough data" before any learning', async () => {
+    const out = await handleBrainTool('brain_metrics', { instance_id: iid }, getConn, noopApiFetch);
+    expect(out).toContain('Brain Metrics');
+    expect(out).toContain('Not enough data');
+  });
+
+  it('always shows the published recall-lift moat number', async () => {
+    const out = await handleBrainTool('brain_metrics', { instance_id: iid }, getConn, noopApiFetch);
+    expect(out).toContain('+22.2 % Precision@1');
+  });
+
+  it('records born_at on first learn (first-wins NX semantics)', async () => {
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:a', outcome: 'success', what_worked: 'x', author: 'alice',
+    }, getConn, noopApiFetch);
+    const born1 = await redis.get(`cachly:stats:born_at:${iid}`);
+    expect(born1).not.toBeNull();
+    // Second learn must NOT overwrite born_at
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:b', outcome: 'success', what_worked: 'y', author: 'bob',
+    }, getConn, noopApiFetch);
+    const born2 = await redis.get(`cachly:stats:born_at:${iid}`);
+    expect(born2).toBe(born1);
+  });
+
+  it('tracks cross-author reuse when one person recalls another\'s lesson', async () => {
+    // Alice stores a proven lesson, recalled once so it counts as "proven"
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:race', outcome: 'success',
+      what_worked: 'add mutex around xyzzy counter', author: 'alice',
+    }, getConn, noopApiFetch);
+    // Bob recalls it (twice → first recall marks proven, second counts reuse on a proven lesson)
+    await handleBrainTool('smart_recall', { instance_id: iid, query: 'xyzzy counter mutex', author: 'bob' }, getConn, noopApiFetch);
+    await handleBrainTool('smart_recall', { instance_id: iid, query: 'xyzzy counter mutex', author: 'bob' }, getConn, noopApiFetch);
+
+    const cross = await redis.get(`cachly:stats:cross_author_recalls:${iid}`);
+    expect(Number(cross)).toBeGreaterThanOrEqual(1);
+
+    const out = await handleBrainTool('brain_metrics', { instance_id: iid }, getConn, noopApiFetch);
+    expect(out).toContain('Team-knowledge-reuse');
+    expect(out).toContain('distinct reuse relationship');
+  });
+
+  it('does not count self-recall as cross-author reuse', async () => {
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:solo', outcome: 'success',
+      what_worked: 'fixed the wibble myself', author: 'alice',
+    }, getConn, noopApiFetch);
+    await handleBrainTool('smart_recall', { instance_id: iid, query: 'wibble', author: 'alice' }, getConn, noopApiFetch);
+    await handleBrainTool('smart_recall', { instance_id: iid, query: 'wibble', author: 'alice' }, getConn, noopApiFetch);
+    const cross = await redis.get(`cachly:stats:cross_author_recalls:${iid}`);
+    expect(Number(cross ?? 0)).toBe(0);
+  });
+
+  it('surfaces the team-reuse banner inline in smart_recall', async () => {
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:plimsoll', outcome: 'success',
+      what_worked: 'adjust the plimsoll threshold', author: 'carol',
+    }, getConn, noopApiFetch);
+    // First recall by dave marks it proven; second recall shows the reuse banner
+    await handleBrainTool('smart_recall', { instance_id: iid, query: 'plimsoll threshold', author: 'dave' }, getConn, noopApiFetch);
+    const out = await handleBrainTool('smart_recall', { instance_id: iid, query: 'plimsoll threshold', author: 'dave' }, getConn, noopApiFetch);
+    expect(out).toContain('Team knowledge reuse');
+  });
+});

package/src/__tests__/utils.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import { EventEmitter } from 'node:events';
+import { safeJsonParse, withTimeout, normalizeGitPath, scanKeys } from '../utils.js';
+
+describe('safeJsonParse', () => {
+  it('parses valid JSON', () => {
+    expect(safeJsonParse('{"a":1}', {})).toEqual({ a: 1 });
+  });
+  it('returns fallback on null/empty/malformed', () => {
+    expect(safeJsonParse(null, 'fb')).toBe('fb');
+    expect(safeJsonParse('', 'fb')).toBe('fb');
+    expect(safeJsonParse('{not json', 'fb')).toBe('fb');
+  });
+});
+
+describe('withTimeout', () => {
+  it('resolves with the promise value when it settles in time', async () => {
+    const out = await withTimeout(Promise.resolve('ok'), 1000, 'fallback');
+    expect(out).toBe('ok');
+  });
+  it('resolves with fallback when the promise is too slow', async () => {
+    const slow = new Promise<string>((r) => setTimeout(() => r('late'), 100));
+    const out = await withTimeout(slow, 10, 'fallback');
+    expect(out).toBe('fallback');
+  });
+  it('resolves with fallback when the promise rejects', async () => {
+    const out = await withTimeout(Promise.reject(new Error('boom')), 1000, 'fallback');
+    expect(out).toBe('fallback');
+  });
+});
+
+describe('normalizeGitPath', () => {
+  it('passes a normal path through', () => {
+    expect(normalizeGitPath('src/auth/jwt.ts')).toBe('src/auth/jwt.ts');
+  });
+  it('resolves brace rename notation to the post-rename path', () => {
+    expect(normalizeGitPath('src/{old => new}/file.ts')).toBe('src/new/file.ts');
+  });
+  it('resolves bare rename notation', () => {
+    expect(normalizeGitPath('old/path.ts => new/path.ts')).toBe('new/path.ts');
+  });
+  it('collapses an empty rename segment cleanly', () => {
+    // dir/{ => sub}/f.ts → dir/sub/f.ts
+    expect(normalizeGitPath('dir/{ => sub}/f.ts')).toBe('dir/sub/f.ts');
+  });
+  it('trims whitespace', () => {
+    expect(normalizeGitPath('  src/x.ts  ')).toBe('src/x.ts');
+  });
+});
+
+// Minimal scan-capable mock
+class ScanMock {
+  constructor(private keys: string[], private opts: { hang?: boolean } = {}) {}
+  scanStream(_o: { match: string; count?: number }) {
+    const em = new EventEmitter();
+    if (this.opts.hang) return em; // never emits — exercises the timeout path
+    setImmediate(() => {
+      em.emit('data', this.keys);
+      em.emit('end');
+    });
+    return em;
+  }
+}
+
+describe('scanKeys', () => {
+  it('collects all matching keys', async () => {
+    const mock = new ScanMock(['a', 'b', 'c']);
+    const out = await scanKeys(mock, 'pattern:*');
+    expect(out).toEqual(['a', 'b', 'c']);
+  });
+  it('caps at max keys', async () => {
+    const mock = new ScanMock(['a', 'b', 'c', 'd', 'e']);
+    const out = await scanKeys(mock, 'pattern:*', { max: 3 });
+    expect(out).toHaveLength(3);
+  });
+  it('resolves with gathered keys on timeout instead of hanging', async () => {
+    const mock = new ScanMock([], { hang: true });
+    const out = await scanKeys(mock, 'pattern:*', { timeoutMs: 20 });
+    expect(out).toEqual([]);
+  });
+});