feat(phase-1): real-time file system watcher (AUTO-01, AUTO-02)

Aitomates · claude · Aitomates · commit fbf6062dc008 · 2026-06-14T15:24:21.000+03:00
- FileWatcher class: chokidar v5 wrapper, two-layer noise filter
- Ignores: node_modules, dist, .git, logs, tmp, coverage
- Watches: ts, js, md, txt, prompt files
- 5 new Vitest tests; 48 total passing
- Wired into server init via RuntimeLogger + CommandCenterDashboard

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/universal-refiner/src/index.ts b/universal-refiner/src/index.ts
@@ -1,9 +1,11 @@
-﻿#!/usr/bin/env node
+#!/usr/bin/env node
 import { PromptRefinerServer } from "./core/server.js";
 import { CommandCenterDashboard } from "./core/dashboard.js";
 import { CommitIngester } from "./history/commit-ingest.js";
 import { CorrelationEngine } from "./history/correlation-engine.js";
 import { LessonExtractor } from "./history/lesson-extractor.js";
+import { FileWatcher } from "./watcher/index.js";
+import { RuntimeLogger } from "./core/logger.js";
 import * as path from "path";
 
 // Start the Web Dashboard in the background
@@ -13,12 +15,21 @@ CommandCenterDashboard.start(port, rootPath);
 
 const server = new PromptRefinerServer(rootPath);
 
+// Phase 1 (AUTO-01, AUTO-02): Real-time file system watcher
+// Starts watching for meaningful source/prompt file changes and logs them.
+const fileWatcher = new FileWatcher(rootPath);
+fileWatcher.on("change", (evt) => {
+  RuntimeLogger.info(`[FS] ${evt.event}: ${evt.path}`);
+  CommandCenterDashboard.log(`[FS] ${evt.event}: ${path.relative(rootPath, evt.path)}`);
+});
+fileWatcher.start();
+
 // Initial background ingestion and correlation
 async function runBackgroundTasks() {
   await CommitIngester.ingestLatest(rootPath);
   const correlation = new CorrelationEngine();
   await correlation.correlateAll();
-  
+
   const extractor = new LessonExtractor((task, prompt, tokens) => server.requestModelText(task, prompt, tokens));
   await extractor.extractNewLessons();
 }
diff --git a/universal-refiner/src/watcher/file-watcher.ts b/universal-refiner/src/watcher/file-watcher.ts
@@ -0,0 +1,159 @@
+import { EventEmitter } from "node:events";
+import { watch as chokidarWatch, FSWatcher } from "chokidar";
+import { RuntimeLogger } from "../core/logger.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type FileEventKind = "add" | "change" | "unlink";
+
+export interface FileChangeEvent {
+  path: string;
+  event: FileEventKind;
+  timestamp: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** File extensions considered "meaningful" for AUTO-01 */
+export const MEANINGFUL_EXTENSIONS = new Set([".ts", ".js", ".md", ".txt", ".prompt"]);
+
+/**
+ * Path segments that mark noise directories (AUTO-02).
+ * Used as a secondary in-process guard after chokidar's ignore patterns.
+ */
+export const NOISE_PATH_SEGMENTS = ["node_modules", "dist", ".git", "coverage"];
+
+/** File suffixes that mark noise files (AUTO-02). */
+export const NOISE_SUFFIXES = [".log", ".tmp"];
+
+/** Paths and patterns passed to chokidar `ignored` option (AUTO-02). */
+const CHOKIDAR_IGNORE: (string | RegExp)[] = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/.git/**",
+  "**/*.log",
+  "**/*.tmp",
+  "**/coverage/**",
+];
+
+// ---------------------------------------------------------------------------
+// FileWatcher
+// ---------------------------------------------------------------------------
+
+/**
+ * FileWatcher wraps chokidar with a focused, typed EventEmitter interface.
+ *
+ * Responsibilities:
+ *  - Detect meaningful source/prompt file changes (AUTO-01)
+ *  - Filter transient/noise paths before emitting (AUTO-02)
+ *
+ * Usage:
+ *   const watcher = new FileWatcher('/path/to/project');
+ *   watcher.on('change', (evt) => console.log(evt));
+ *   watcher.start();
+ *   // later
+ *   await watcher.stop();
+ */
+export class FileWatcher extends EventEmitter {
+  private readonly rootPath: string;
+  private inner: FSWatcher | null = null;
+
+  constructor(rootPath: string) {
+    super();
+    this.rootPath = rootPath;
+  }
+
+  // ------------------------------------------------------------------
+  // Public API
+  // ------------------------------------------------------------------
+
+  /** Start watching. Idempotent — calling twice is a no-op. */
+  public start(): void {
+    if (this.inner) {
+      return;
+    }
+
+    RuntimeLogger.info("[FileWatcher] Starting file system watcher", {
+      rootPath: this.rootPath,
+    });
+
+    this.inner = chokidarWatch(this.rootPath, {
+      ignored: CHOKIDAR_IGNORE,
+      persistent: true,
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 100,
+        pollInterval: 50,
+      },
+    });
+
+    this.inner.on("add", (filePath) => this.emitChange("add", filePath));
+    this.inner.on("change", (filePath) => this.emitChange("change", filePath));
+    this.inner.on("unlink", (filePath) => this.emitChange("unlink", filePath));
+    this.inner.on("error", (err: unknown) => {
+      RuntimeLogger.error("[FileWatcher] Watcher error", err);
+      this.emit("error", err instanceof Error ? err : new Error(String(err)));
+    });
+  }
+
+  /** Stop watching and release all resources. */
+  public async stop(): Promise<void> {
+    if (!this.inner) {
+      return;
+    }
+    await this.inner.close();
+    this.inner = null;
+    RuntimeLogger.info("[FileWatcher] Stopped file system watcher");
+  }
+
+  // ------------------------------------------------------------------
+  // Internal helpers
+  // ------------------------------------------------------------------
+
+  /**
+   * Apply both AUTO-01 and AUTO-02 filters before emitting.
+   *
+   * Two-layer defence:
+   *  1. chokidar `ignored` patterns (coarse, path-glob based)
+   *  2. In-process extension + segment checks (precise, cross-platform)
+   *
+   * The in-process layer catches edge cases where chokidar's glob ignore
+   * may lag (e.g. directories created before the watcher starts on Windows).
+   */
+  private emitChange(kind: FileEventKind, filePath: string): void {
+    // Normalise separators for consistent matching on Windows
+    const normalised = filePath.replace(/\\/g, "/");
+
+    // AUTO-02: segment-level noise filter
+    for (const seg of NOISE_PATH_SEGMENTS) {
+      if (normalised.includes(`/${seg}/`) || normalised.includes(`/${seg}`)) {
+        return;
+      }
+    }
+
+    // AUTO-01: extension filter — only emit for meaningful file types
+    const dotIdx = normalised.lastIndexOf(".");
+    const ext = dotIdx >= 0 ? normalised.slice(dotIdx).toLowerCase() : "";
+
+    // AUTO-02: suffix-level noise filter (e.g. .log, .tmp)
+    if (NOISE_SUFFIXES.includes(ext)) {
+      return;
+    }
+
+    if (!MEANINGFUL_EXTENSIONS.has(ext)) {
+      return;
+    }
+
+    const evt: FileChangeEvent = {
+      path: filePath,
+      event: kind,
+      timestamp: new Date(),
+    };
+    RuntimeLogger.debug(`[FileWatcher] ${kind}: ${filePath}`);
+    this.emit("change", evt);
+  }
+}
diff --git a/universal-refiner/src/watcher/index.ts b/universal-refiner/src/watcher/index.ts
@@ -0,0 +1,2 @@
+export { FileWatcher } from "./file-watcher.js";
+export type { FileChangeEvent, FileEventKind } from "./file-watcher.js";
diff --git a/universal-refiner/tests/file-watcher.test.ts b/universal-refiner/tests/file-watcher.test.ts
@@ -0,0 +1,165 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { FileWatcher, FileChangeEvent } from "../src/watcher/file-watcher.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wait up to `timeout` ms for `predicate` to return true, polling every `interval` ms.
+ * Provides a clear assertion failure message on timeout.
+ */
+function waitFor(
+  predicate: () => boolean,
+  timeout = 6000,
+  interval = 50
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeout;
+    const timer = setInterval(() => {
+      if (predicate()) {
+        clearInterval(timer);
+        resolve();
+      } else if (Date.now() > deadline) {
+        clearInterval(timer);
+        reject(new Error("waitFor: timeout exceeded"));
+      }
+    }, interval);
+  });
+}
+
+/**
+ * Wait for chokidar to finish setting up FS listeners.
+ * Windows FSEvents/polling can need 500-1500ms before reliably firing.
+ */
+const WATCHER_SETTLE_MS = 1500;
+
+// ---------------------------------------------------------------------------
+// Suite
+// ---------------------------------------------------------------------------
+
+describe("FileWatcher", () => {
+  let tmpDir: string;
+  let watcher: FileWatcher;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fw-test-"));
+  });
+
+  afterEach(async () => {
+    if (watcher) {
+      await watcher.stop();
+    }
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // -----------------------------------------------------------------------
+  // AUTO-01: detect meaningful file changes
+  // -----------------------------------------------------------------------
+
+  it("detects a file write as a 'change' event (AUTO-01)", async () => {
+    // Create file before watcher starts so initial scan won't fire 'add'
+    const filePath = path.join(tmpDir, "test.ts");
+    fs.writeFileSync(filePath, "// initial");
+
+    const events: FileChangeEvent[] = [];
+    watcher = new FileWatcher(tmpDir);
+    watcher.on("change", (evt) => events.push(evt));
+    watcher.start();
+
+    // Allow chokidar to finish indexing the directory
+    await new Promise((r) => setTimeout(r, WATCHER_SETTLE_MS));
+
+    // Modify the file
+    fs.writeFileSync(filePath, "// updated");
+
+    // Wait for event
+    await waitFor(() => events.some((e) => e.event === "change" && e.path.endsWith("test.ts")));
+
+    const hit = events.find((e) => e.event === "change");
+    expect(hit).toBeDefined();
+    expect(hit!.path).toContain("test.ts");
+    expect(hit!.timestamp).toBeInstanceOf(Date);
+  }, 15_000);
+
+  it("detects a new file as an 'add' event (AUTO-01)", async () => {
+    const events: FileChangeEvent[] = [];
+    watcher = new FileWatcher(tmpDir);
+    watcher.on("change", (evt) => events.push(evt));
+    watcher.start();
+
+    await new Promise((r) => setTimeout(r, WATCHER_SETTLE_MS));
+
+    fs.writeFileSync(path.join(tmpDir, "new.ts"), "export {}");
+
+    await waitFor(() => events.some((e) => e.event === "add" && e.path.endsWith("new.ts")));
+
+    const hit = events.find((e) => e.event === "add");
+    expect(hit).toBeDefined();
+    expect(hit!.event).toBe("add");
+    expect(hit!.timestamp).toBeInstanceOf(Date);
+  }, 15_000);
+
+  // -----------------------------------------------------------------------
+  // AUTO-02: noise filter
+  // -----------------------------------------------------------------------
+
+  it("does NOT emit events for paths inside node_modules (AUTO-02)", async () => {
+    const nmDir = path.join(tmpDir, "node_modules", "some-pkg");
+    fs.mkdirSync(nmDir, { recursive: true });
+
+    const events: FileChangeEvent[] = [];
+    watcher = new FileWatcher(tmpDir);
+    watcher.on("change", (evt) => events.push(evt));
+    watcher.start();
+
+    await new Promise((r) => setTimeout(r, WATCHER_SETTLE_MS));
+
+    fs.writeFileSync(path.join(nmDir, "index.ts"), "// ignored");
+
+    // Wait and assert silence
+    await new Promise((r) => setTimeout(r, 800));
+    const nmEvents = events.filter((e) => e.path.includes("node_modules"));
+    expect(nmEvents).toHaveLength(0);
+  }, 15_000);
+
+  it("does NOT emit events for *.log files (AUTO-02)", async () => {
+    const events: FileChangeEvent[] = [];
+    watcher = new FileWatcher(tmpDir);
+    watcher.on("change", (evt) => events.push(evt));
+    watcher.start();
+
+    await new Promise((r) => setTimeout(r, WATCHER_SETTLE_MS));
+
+    fs.writeFileSync(path.join(tmpDir, "debug.log"), "some log line");
+
+    await new Promise((r) => setTimeout(r, 800));
+    expect(events.filter((e) => e.path.endsWith(".log"))).toHaveLength(0);
+  }, 15_000);
+
+  // -----------------------------------------------------------------------
+  // stop() — no further events after stop
+  // -----------------------------------------------------------------------
+
+  it("stop() prevents further events from being emitted", async () => {
+    const filePath = path.join(tmpDir, "track.ts");
+    fs.writeFileSync(filePath, "// v1");
+
+    const events: FileChangeEvent[] = [];
+    watcher = new FileWatcher(tmpDir);
+    watcher.on("change", (evt) => events.push(evt));
+    watcher.start();
+
+    await new Promise((r) => setTimeout(r, WATCHER_SETTLE_MS));
+    await watcher.stop();
+
+    const countBefore = events.length;
+    fs.writeFileSync(filePath, "// v2");
+    await new Promise((r) => setTimeout(r, 800));
+
+    expect(events.length).toBe(countBefore);
+  }, 15_000);
+});

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export { FileWatcher } from "./file-watcher.js";`
	`2`	`+export type { FileChangeEvent, FileEventKind } from "./file-watcher.js";`