feat(watcher): chokidar auto-refresh with debounced incremental reindex

Adds a chokidar-based file watcher that runs in MCP server mode.
Any source file change in the project root triggers a debounced
incremental reindex automatically — no manual refresh_index needed.

- src/core/file-watcher.ts: FileWatcherOptions interface + startFileWatcher()
  with configurable debounce (default 2 s, override via CODEBASE_CONTEXT_DEBOUNCE_MS)
- src/index.ts: wires watcher after server.connect(), guards against
  concurrent reindexes with indexState.status check, cleans up on exit/SIGINT/SIGTERM
- tests/file-watcher.test.ts: 3 vitest tests covering trigger, debounce
  coalescing, and stop() cancellation (real fs writes, no fake timers)
- package.json: adds chokidar ^3.6.0 dependency

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: PatrickSys

package.json

@@ -126,6 +126,7 @@
     "@lancedb/lancedb": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@typescript-eslint/typescript-estree": "^7.0.0",
+    "chokidar": "^3.6.0",
     "fuse.js": "^7.0.0",
     "glob": "^10.3.10",
     "hono": "^4.12.2",

pnpm-lock.yaml

@@ -0,0 +1,44 @@
+import chokidar from 'chokidar';
+
+export interface FileWatcherOptions {
+  rootPath: string;
+  /** ms after last change before triggering. Default: 2000 */
+  debounceMs?: number;
+  /** Called once the debounce window expires after the last detected change */
+  onChanged: () => void;
+}
+
+/**
+ * Watch rootPath for source file changes and call onChanged (debounced).
+ * Returns a stop() function that cancels the debounce timer and closes the watcher.
+ */
+export function startFileWatcher(opts: FileWatcherOptions): () => void {
+  const { rootPath, debounceMs = 2000, onChanged } = opts;
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const trigger = () => {
+    if (debounceTimer !== undefined) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = undefined;
+      onChanged();
+    }, debounceMs);
+  };
+
+  const watcher = chokidar.watch(rootPath, {
+    ignored: ['**/node_modules/**', '**/.codebase-context/**', '**/.git/**', '**/dist/**'],
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 100 }
+  });
+
+  watcher
+    .on('add', trigger)
+    .on('change', trigger)
+    .on('unlink', trigger)
+    .on('error', (err: unknown) => console.error('[file-watcher] error:', err));
+
+  return () => {
+    if (debounceTimer !== undefined) clearTimeout(debounceTimer);
+    void watcher.close();
+  };
+}

src/core/file-watcher.ts

@@ -38,6 +38,7 @@ import {
 } from './constants/codebase-context.js';
 import { appendMemoryFile } from './memory/store.js';
 import { handleCliCommand } from './cli.js';
+import { startFileWatcher } from './core/file-watcher.js';
 import { parseGitLogLineToMemory } from './memory/git-memory.js';
 import {
   isComplementaryPatternCategory,
@@ -726,6 +727,33 @@ async function main() {
   await server.connect(transport);
 
   if (process.env.CODEBASE_CONTEXT_DEBUG) console.error('[DEBUG] Server ready');
+
+  // Auto-refresh: watch for file changes and trigger incremental reindex
+  const debounceMs = parseInt(process.env.CODEBASE_CONTEXT_DEBOUNCE_MS ?? '', 10) || 2000;
+  const stopWatcher = startFileWatcher({
+    rootPath: ROOT_PATH,
+    debounceMs,
+    onChanged: () => {
+      if (indexState.status === 'indexing') {
+        if (process.env.CODEBASE_CONTEXT_DEBUG) {
+          console.error('[file-watcher] Index in progress — skipping auto-refresh');
+        }
+        return;
+      }
+      console.error('[file-watcher] Changes detected — incremental reindex starting');
+      performIndexing(true);
+    }
+  });
+
+  process.once('exit', stopWatcher);
+  process.once('SIGINT', () => {
+    stopWatcher();
+    process.exit(0);
+  });
+  process.once('SIGTERM', () => {
+    stopWatcher();
+    process.exit(0);
+  });
 }
 
 // Export server components for programmatic use

src/index.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { startFileWatcher } from '../src/core/file-watcher.js';
+
+describe('FileWatcher', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'file-watcher-test-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('triggers onChanged after debounce window', async () => {
+    const debounceMs = 400;
+    let callCount = 0;
+
+    const stop = startFileWatcher({
+      rootPath: tempDir,
+      debounceMs,
+      onChanged: () => { callCount++; },
+    });
+
+    try {
+      // Give chokidar a moment to finish initializing before the first write
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      await fs.writeFile(path.join(tempDir, 'test.ts'), 'export const x = 1;');
+      // Wait for chokidar to pick up the event (including awaitWriteFinish stabilityThreshold)
+      // + debounce window + OS scheduling slack
+      await new Promise((resolve) => setTimeout(resolve, debounceMs + 1000));
+      expect(callCount).toBe(1);
+    } finally {
+      stop();
+    }
+  }, 8000);
+
+  it('debounces rapid changes into a single callback', async () => {
+    const debounceMs = 300;
+    let callCount = 0;
+
+    const stop = startFileWatcher({
+      rootPath: tempDir,
+      debounceMs,
+      onChanged: () => { callCount++; },
+    });
+
+    try {
+      // Write 5 files in quick succession — all within the debounce window
+      for (let i = 0; i < 5; i++) {
+        await fs.writeFile(path.join(tempDir, `file${i}.ts`), `export const x${i} = ${i};`);
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      }
+      // Wait for debounce to settle
+      await new Promise((resolve) => setTimeout(resolve, debounceMs + 400));
+      expect(callCount).toBe(1);
+    } finally {
+      stop();
+    }
+  }, 8000);
+
+  it('stop() cancels a pending callback', async () => {
+    const debounceMs = 500;
+    let callCount = 0;
+
+    const stop = startFileWatcher({
+      rootPath: tempDir,
+      debounceMs,
+      onChanged: () => { callCount++; },
+    });
+
+    await fs.writeFile(path.join(tempDir, 'cancel.ts'), 'export const y = 99;');
+    // Let chokidar detect the event but stop before debounce fires
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    stop();
+    // Wait past where debounce would have fired
+    await new Promise((resolve) => setTimeout(resolve, debounceMs + 200));
+    expect(callCount).toBe(0);
+  }, 5000);
+});