cognitive-core 0.1.0 → 0.2.0

package/references/minimem/src/cli/sync/validation.ts

@@ -0,0 +1,206 @@
+/**
+ * Registry validation
+ *
+ * Validates registry for path collisions, stale mappings, and missing directories.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { readRegistry, type Registry, type RegistryMapping } from "./registry.js";
+import { getCentralRepoPath } from "./central.js";
+import { loadXdgConfig } from "../config.js";
+
+export type ValidationIssue = {
+  type: "collision" | "stale" | "missing" | "orphan";
+  severity: "warning" | "error";
+  message: string;
+  path?: string;
+  machineId?: string;
+  details?: Record<string, unknown>;
+};
+
+export type ValidationResult = {
+  valid: boolean;
+  issues: ValidationIssue[];
+  stats: {
+    totalMappings: number;
+    activeMappings: number;
+    staleMappings: number;
+    collisions: number;
+    missingDirs: number;
+  };
+};
+
+const STALE_THRESHOLD_DAYS = 30;
+
+/**
+ * Validate the registry
+ */
+export async function validateRegistry(): Promise<ValidationResult> {
+  const result: ValidationResult = {
+    valid: true,
+    issues: [],
+    stats: {
+      totalMappings: 0,
+      activeMappings: 0,
+      staleMappings: 0,
+      collisions: 0,
+      missingDirs: 0,
+    },
+  };
+
+  const centralRepo = await getCentralRepoPath();
+  if (!centralRepo) {
+    result.issues.push({
+      type: "missing",
+      severity: "warning",
+      message: "No central repository configured",
+    });
+    return result;
+  }
+
+  let registry: Registry;
+  try {
+    registry = await readRegistry(centralRepo);
+  } catch (error) {
+    result.issues.push({
+      type: "missing",
+      severity: "error",
+      message: `Failed to read registry: ${error}`,
+    });
+    result.valid = false;
+    return result;
+  }
+
+  const xdgConfig = await loadXdgConfig();
+  const currentMachineId = xdgConfig.machineId;
+  const now = new Date();
+  const staleThreshold = new Date(now.getTime() - STALE_THRESHOLD_DAYS * 24 * 60 * 60 * 1000);
+
+  result.stats.totalMappings = registry.mappings.length;
+
+  // Group mappings by central path to detect collisions
+  const pathToMappings = new Map<string, RegistryMapping[]>();
+
+  for (const mapping of registry.mappings) {
+    const existing = pathToMappings.get(mapping.path) || [];
+    existing.push(mapping);
+    pathToMappings.set(mapping.path, existing);
+  }
+
+  // Check for collisions
+  for (const [centralPath, mappings] of pathToMappings) {
+    if (mappings.length > 1) {
+      // Multiple machines mapping to same path
+      const machineIds = mappings.map((m) => m.machineId);
+      const uniqueMachines = new Set(machineIds);
+
+      if (uniqueMachines.size > 1) {
+        result.issues.push({
+          type: "collision",
+          severity: "error",
+          message: `Path '${centralPath}' is mapped by multiple machines: ${Array.from(uniqueMachines).join(", ")}`,
+          path: centralPath,
+          details: { machines: Array.from(uniqueMachines) },
+        });
+        result.stats.collisions++;
+        result.valid = false;
+      }
+    }
+  }
+
+  // Check each mapping
+  for (const mapping of registry.mappings) {
+    // Check for stale mappings
+    const lastSyncDate = new Date(mapping.lastSync);
+    if (lastSyncDate < staleThreshold) {
+      const daysSinceSync = Math.floor(
+        (now.getTime() - lastSyncDate.getTime()) / (24 * 60 * 60 * 1000)
+      );
+
+      result.issues.push({
+        type: "stale",
+        severity: "warning",
+        message: `Mapping '${mapping.path}' by '${mapping.machineId}' is stale (last sync: ${daysSinceSync} days ago)`,
+        path: mapping.path,
+        machineId: mapping.machineId,
+        details: { lastSync: mapping.lastSync, daysSinceSync },
+      });
+      result.stats.staleMappings++;
+    } else {
+      result.stats.activeMappings++;
+    }
+
+    // Check if local directory exists (only for current machine)
+    if (mapping.machineId === currentMachineId) {
+      const localPath = expandPath(mapping.localPath);
+      try {
+        await fs.access(localPath);
+      } catch {
+        result.issues.push({
+          type: "missing",
+          severity: "warning",
+          message: `Local directory no longer exists: ${mapping.localPath}`,
+          path: mapping.path,
+          machineId: mapping.machineId,
+          details: { localPath: mapping.localPath },
+        });
+        result.stats.missingDirs++;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Expand path (handle ~ for home directory)
+ */
+function expandPath(p: string): string {
+  if (p.startsWith("~/")) {
+    return path.join(process.env.HOME || "", p.slice(2));
+  }
+  return p;
+}
+
+/**
+ * Format validation result for display
+ */
+export function formatValidationResult(result: ValidationResult): string {
+  const lines: string[] = [];
+
+  lines.push("Registry Validation Results");
+  lines.push("-".repeat(40));
+
+  lines.push(`Total mappings: ${result.stats.totalMappings}`);
+  lines.push(`Active mappings: ${result.stats.activeMappings}`);
+
+  if (result.stats.staleMappings > 0) {
+    lines.push(`Stale mappings: ${result.stats.staleMappings}`);
+  }
+  if (result.stats.collisions > 0) {
+    lines.push(`Collisions: ${result.stats.collisions}`);
+  }
+  if (result.stats.missingDirs > 0) {
+    lines.push(`Missing directories: ${result.stats.missingDirs}`);
+  }
+
+  if (result.issues.length > 0) {
+    lines.push("");
+    lines.push("Issues:");
+
+    for (const issue of result.issues) {
+      const prefix = issue.severity === "error" ? "ERROR" : "WARN";
+      lines.push(`  [${prefix}] ${issue.message}`);
+    }
+  } else {
+    lines.push("");
+    lines.push("No issues found.");
+  }
+
+  lines.push("");
+  lines.push(result.valid ? "Registry is valid." : "Registry has errors that need attention.");
+
+  return lines.join("\n");
+}

package/references/minimem/src/cli/sync/watcher.ts

@@ -0,0 +1,234 @@
+/**
+ * File watcher with debouncing for memory directories
+ */
+
+import chokidar, { type FSWatcher } from "chokidar";
+import path from "node:path";
+import { EventEmitter } from "node:events";
+
+import { listSyncableFiles } from "./state.js";
+
+export type WatcherEvent = "add" | "change" | "unlink";
+
+export type FileChange = {
+  event: WatcherEvent;
+  file: string; // Relative path
+};
+
+export type WatcherOptions = {
+  /** Debounce interval in milliseconds (default: 2000) */
+  debounceMs?: number;
+  /** Patterns to include (default: MEMORY.md, memory/*.md) */
+  include?: string[];
+  /** Patterns to exclude */
+  exclude?: string[];
+  /** Use polling instead of native events (for network drives) */
+  usePolling?: boolean;
+  /** Polling interval in milliseconds (default: 1000) */
+  pollInterval?: number;
+};
+
+export type WatcherInstance = {
+  /** Stop watching and clean up */
+  close: () => Promise<void>;
+  /** Add event listener */
+  on: (event: "changes", listener: (changes: FileChange[]) => void) => void;
+  /** Remove event listener */
+  off: (event: "changes", listener: (changes: FileChange[]) => void) => void;
+  /** Whether the watcher is ready */
+  ready: boolean;
+};
+
+const DEFAULT_DEBOUNCE_MS = 2000;
+const DEFAULT_POLL_INTERVAL = 1000;
+
+const DEFAULT_INCLUDE = ["MEMORY.md", "memory/**/*.md"];
+const DEFAULT_EXCLUDE = [".minimem/**", "node_modules/**", ".git/**"];
+
+/**
+ * Create a file watcher for a memory directory
+ */
+export function createFileWatcher(
+  memoryDir: string,
+  options: WatcherOptions = {}
+): WatcherInstance {
+  const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const include = options.include ?? DEFAULT_INCLUDE;
+  const exclude = options.exclude ?? DEFAULT_EXCLUDE;
+
+  const emitter = new EventEmitter();
+  let watcher: FSWatcher | null = null;
+  let ready = false;
+
+  // Pending changes for debouncing
+  let pendingChanges: Map<string, FileChange> = new Map();
+  let debounceTimer: NodeJS.Timeout | null = null;
+
+  /**
+   * Flush pending changes
+   */
+  const flushChanges = () => {
+    if (pendingChanges.size > 0) {
+      const changes = Array.from(pendingChanges.values());
+      pendingChanges = new Map();
+      emitter.emit("changes", changes);
+    }
+    debounceTimer = null;
+  };
+
+  /**
+   * Schedule a debounced flush
+   */
+  const scheduleFlush = () => {
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(flushChanges, debounceMs);
+  };
+
+  /**
+   * Handle a file event
+   */
+  const handleEvent = (event: WatcherEvent, filePath: string) => {
+    // Get relative path
+    const relativePath = path.relative(memoryDir, filePath);
+
+    // Skip files in .minimem
+    if (relativePath.startsWith(".minimem")) {
+      return;
+    }
+
+    // Check if file matches include patterns
+    const isIncluded = include.some((pattern) => {
+      if (pattern.includes("*")) {
+        // Simple glob matching
+        const regex = new RegExp(
+          "^" + pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*") + "$"
+        );
+        return regex.test(relativePath);
+      }
+      return relativePath === pattern || relativePath.startsWith(pattern + "/");
+    });
+
+    if (!isIncluded) {
+      return;
+    }
+
+    // Check if file matches exclude patterns
+    const isExcluded = exclude.some((pattern) => {
+      if (pattern.includes("*")) {
+        const regex = new RegExp(
+          "^" + pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*") + "$"
+        );
+        return regex.test(relativePath);
+      }
+      return relativePath === pattern || relativePath.startsWith(pattern);
+    });
+
+    if (isExcluded) {
+      return;
+    }
+
+    // Add to pending changes (later events override earlier for same file)
+    pendingChanges.set(relativePath, { event, file: relativePath });
+    scheduleFlush();
+  };
+
+  // Create watcher
+  const watchPaths = include.map((pattern) => path.join(memoryDir, pattern));
+
+  watcher = chokidar.watch(watchPaths, {
+    ignored: exclude.map((pattern) => path.join(memoryDir, pattern)),
+    persistent: true,
+    ignoreInitial: true,
+    usePolling: options.usePolling ?? false,
+    interval: options.pollInterval ?? DEFAULT_POLL_INTERVAL,
+    awaitWriteFinish: {
+      stabilityThreshold: 500,
+      pollInterval: 100,
+    },
+  });
+
+  watcher
+    .on("add", (filePath) => handleEvent("add", filePath))
+    .on("change", (filePath) => handleEvent("change", filePath))
+    .on("unlink", (filePath) => handleEvent("unlink", filePath))
+    .on("ready", () => {
+      ready = true;
+    })
+    .on("error", (error) => {
+      console.error(`Watcher error: ${error}`);
+    });
+
+  return {
+    close: async () => {
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      if (watcher) {
+        await watcher.close();
+        watcher = null;
+      }
+      emitter.removeAllListeners();
+    },
+
+    on: (event: "changes", listener: (changes: FileChange[]) => void) => {
+      emitter.on(event, listener);
+    },
+
+    off: (event: "changes", listener: (changes: FileChange[]) => void) => {
+      emitter.off(event, listener);
+    },
+
+    get ready() {
+      return ready;
+    },
+  };
+}
+
+/**
+ * Watch multiple directories
+ */
+export function createMultiDirWatcher(
+  memoryDirs: string[],
+  options: WatcherOptions = {}
+): WatcherInstance {
+  const watchers = memoryDirs.map((dir) => ({
+    dir,
+    watcher: createFileWatcher(dir, options),
+  }));
+
+  const emitter = new EventEmitter();
+
+  // Forward events from all watchers
+  for (const { dir, watcher } of watchers) {
+    watcher.on("changes", (changes) => {
+      // Add directory info to changes
+      const changesWithDir = changes.map((c) => ({
+        ...c,
+        file: path.join(dir, c.file),
+      }));
+      emitter.emit("changes", changesWithDir);
+    });
+  }
+
+  return {
+    close: async () => {
+      await Promise.all(watchers.map(({ watcher }) => watcher.close()));
+      emitter.removeAllListeners();
+    },
+
+    on: (event: "changes", listener: (changes: FileChange[]) => void) => {
+      emitter.on(event, listener);
+    },
+
+    off: (event: "changes", listener: (changes: FileChange[]) => void) => {
+      emitter.off(event, listener);
+    },
+
+    get ready() {
+      return watchers.every(({ watcher }) => watcher.ready);
+    },
+  };
+}

package/references/minimem/src/cli/version.ts

@@ -0,0 +1,34 @@
+/**
+ * Version management for the CLI
+ *
+ * Reads the version from package.json at runtime for consistency.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Get the package version from package.json
+ *
+ * This reads from the package.json at runtime to ensure the CLI
+ * version always matches the published package version.
+ */
+function getPackageVersion(): string {
+  try {
+    // In ESM, we need to get __dirname equivalent
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+
+    // Navigate from src/cli/ to package root
+    const packagePath = join(__dirname, "../../package.json");
+    const packageJson = JSON.parse(readFileSync(packagePath, "utf-8"));
+    return packageJson.version || "0.0.0";
+  } catch {
+    // Fallback if we can't read package.json
+    // This might happen in bundled builds where path resolution differs
+    return "0.0.0";
+  }
+}
+
+export const VERSION = getPackageVersion();

package/references/minimem/src/core/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Core module - Indexer and Searcher components
+ *
+ * These classes extract indexing and search concerns from the Minimem class
+ * to improve separation of concerns and testability.
+ */
+
+export { MemoryIndexer, type IndexerConfig, type MemoryIndexMeta, type IndexStats } from "./indexer.js";
+export { MemorySearcher, type SearchConfig, type SearchResult } from "./searcher.js";