memorylink 1.0.0

package/src/commands/validate.ts

@@ -0,0 +1,191 @@
+/**
+ * MemoryLink - Validate Command
+ * Batch validation and quality report
+ * 
+ * v1.3: Week 5 - Memory Quality Validation
+ */
+
+import {
+  getFilePath,
+  isInitialized,
+  error,
+  info,
+  warn,
+  success,
+  findRoot,
+  readJsonlEntries,
+  isJsonlFormat,
+} from '../utils.js';
+import {
+  scoreMemoryEntry,
+  scoreLearningEntry,
+  getQualityLevel,
+  formatQualityScore,
+  type QualityScore,
+} from '../utils/quality.js';
+import type { MemoryEntry, LearningEntry, GlobalOptions } from '../types.js';
+
+interface ValidationReport {
+  total: number;
+  excellent: number;
+  good: number;
+  acceptable: number;
+  poor: number;
+  averageScore: number;
+  lowQualityEntries: Array<{
+    id: string;
+    type: 'memory' | 'learning';
+    score: number;
+    issues: string[];
+    preview: string;
+  }>;
+}
+
+export async function validateCommand(
+  options: GlobalOptions & { fix?: boolean } = {}
+): Promise<void> {
+  const { verbose, fix = false } = options;
+
+  // Check initialization
+  const root = findRoot();
+  if (!root || !isInitialized(root)) {
+    error('MemoryLink is not initialized. Run: memorylink init');
+    process.exit(1);
+  }
+
+  const memoryPath = getFilePath('MEMORY', root);
+  const learningsPath = getFilePath('LEARNINGS', root);
+
+  const report: ValidationReport = {
+    total: 0,
+    excellent: 0,
+    good: 0,
+    acceptable: 0,
+    poor: 0,
+    averageScore: 0,
+    lowQualityEntries: [],
+  };
+
+  const allScores: number[] = [];
+
+  // Validate memory entries
+  if (isJsonlFormat(memoryPath)) {
+    const entries = readJsonlEntries<MemoryEntry>(memoryPath)
+      .filter(e => e.status === 'ACTIVE');
+
+    for (const entry of entries) {
+      const qualityScore = scoreMemoryEntry(entry);
+      allScores.push(qualityScore.score);
+      report.total++;
+
+      const level = getQualityLevel(qualityScore.score);
+      if (level === 'excellent') report.excellent++;
+      else if (level === 'good') report.good++;
+      else if (level === 'acceptable') report.acceptable++;
+      else report.poor++;
+
+      if (qualityScore.score < 60) {
+        report.lowQualityEntries.push({
+          id: entry.id,
+          type: 'memory',
+          score: qualityScore.score,
+          issues: qualityScore.issues,
+          preview: entry.details?.substring(0, 60) || '',
+        });
+      }
+    }
+  }
+
+  // Validate learning entries
+  if (isJsonlFormat(learningsPath)) {
+    const entries = readJsonlEntries<LearningEntry>(learningsPath)
+      .filter(e => e.status === 'ACTIVE');
+
+    for (const entry of entries) {
+      const qualityScore = scoreLearningEntry(entry);
+      allScores.push(qualityScore.score);
+      report.total++;
+
+      const level = getQualityLevel(qualityScore.score);
+      if (level === 'excellent') report.excellent++;
+      else if (level === 'good') report.good++;
+      else if (level === 'acceptable') report.acceptable++;
+      else report.poor++;
+
+      if (qualityScore.score < 60) {
+        report.lowQualityEntries.push({
+          id: entry.id,
+          type: 'learning',
+          score: qualityScore.score,
+          issues: qualityScore.issues,
+          preview: entry.problem?.substring(0, 60) || '',
+        });
+      }
+    }
+  }
+
+  // Calculate average
+  if (allScores.length > 0) {
+    report.averageScore = Math.round(
+      allScores.reduce((a, b) => a + b, 0) / allScores.length
+    );
+  }
+
+  // Display report
+  console.log('');
+  info('📊 MemoryLink Quality Report');
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log('');
+  console.log(`Total entries: ${report.total}`);
+  console.log(`Average score: ${report.averageScore}/100`);
+  console.log('');
+  console.log('Quality distribution:');
+  console.log(`  🌟 Excellent (80+): ${report.excellent} (${report.total > 0 ? Math.round((report.excellent / report.total) * 100) : 0}%)`);
+  console.log(`  ✅ Good (60-79):    ${report.good} (${report.total > 0 ? Math.round((report.good / report.total) * 100) : 0}%)`);
+  console.log(`  ⚠️  Acceptable (40-59): ${report.acceptable} (${report.total > 0 ? Math.round((report.acceptable / report.total) * 100) : 0}%)`);
+  console.log(`  ❌ Poor (<40):      ${report.poor} (${report.total > 0 ? Math.round((report.poor / report.total) * 100) : 0}%)`);
+  console.log('');
+
+  // Show low-quality entries
+  if (report.lowQualityEntries.length > 0) {
+    console.log(`⚠️  Low-quality entries (score < 60): ${report.lowQualityEntries.length}`);
+    console.log('');
+    
+    // Show top 10 worst entries
+    const worstEntries = report.lowQualityEntries
+      .sort((a, b) => a.score - b.score)
+      .slice(0, 10);
+
+    worstEntries.forEach((entry, idx) => {
+      console.log(`${idx + 1}. [${entry.type.toUpperCase()}] Score: ${entry.score}/100`);
+      console.log(`   Preview: ${entry.preview}...`);
+      console.log(`   Issues: ${entry.issues.join(', ')}`);
+      console.log('');
+    });
+
+    if (report.lowQualityEntries.length > 10) {
+      console.log(`   ... and ${report.lowQualityEntries.length - 10} more`);
+      console.log('');
+    }
+
+    if (fix) {
+      warn('--fix option not yet implemented. Use suggestions above to improve entries manually.');
+      console.log('');
+    }
+  } else {
+    success('All entries meet quality standards!');
+    console.log('');
+  }
+
+  // Suggestions
+  if (report.averageScore < 70) {
+    console.log('💡 Suggestions to improve overall quality:');
+    console.log('  • Add more details to entries');
+    console.log('  • Use specific language (avoid vague words)');
+    console.log('  • Add tags to improve searchability');
+    console.log('  • Link entries to files when relevant');
+    console.log('  • Specify outcomes for learnings (SUCCESS/FAILED)');
+    console.log('');
+  }
+}
+

package/src/commands/watch-preferences.ts

@@ -0,0 +1,162 @@
+/**
+ * MemoryLink - Watch Preferences Command
+ * File watcher for real-time preference updates
+ * 
+ * AGENT NEED: Preferences automatically reloaded when changed
+ * USER NEED: "It just works" - no manual restart needed
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as chokidar from 'chokidar';
+import {
+  findRoot,
+  isInitialized,
+  getFilePath,
+  success,
+  error,
+  warn,
+  info,
+  log,
+} from '../utils.js';
+import type { GlobalOptions } from '../types.js';
+import { syncRulesCommand } from './sync-rules.js';
+
+let preferenceWatcher: chokidar.FSWatcher | null = null;
+
+/**
+ * Watch for preference changes and auto-reload AI tool configs
+ */
+export async function watchPreferencesCommand(options: GlobalOptions = {}): Promise<void> {
+  const { verbose } = options;
+
+  log('Starting preference watcher...', verbose);
+
+  const root = findRoot();
+  if (!root || !isInitialized(root)) {
+    error('MemoryLink is not initialized. Run: memorylink init');
+    process.exit(1);
+  }
+
+  const memoryPath = getFilePath('MEMORY', root);
+  const rulesPath = path.join(root, '.memorylink', 'rules.md');
+
+  // Stop existing watcher if any
+  if (preferenceWatcher) {
+    await preferenceWatcher.close();
+  }
+
+  console.log('');
+  info('🔍 MemoryLink Preference Watcher');
+  console.log('');
+  info('Watching for preference/rule changes...');
+  info('Press Ctrl+C to stop');
+  console.log('');
+
+  // Create watcher for memory.log and rules.md
+  preferenceWatcher = chokidar.watch([memoryPath, rulesPath], {
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 500,
+      pollInterval: 100,
+    },
+  });
+
+  let isProcessing = false;
+
+  preferenceWatcher.on('change', async (filePath: string) => {
+    if (isProcessing) {
+      return; // Prevent concurrent processing
+    }
+
+    isProcessing = true;
+
+    try {
+      const fileName = path.basename(filePath);
+      
+      if (fileName === 'memory.log') {
+        log('Memory log changed, checking for new preferences/rules...', verbose);
+        
+        // Read memory.log to check for new rules/preferences
+        const content = fs.readFileSync(memoryPath, 'utf-8');
+        const lines = content.split('\n').filter(l => l.trim());
+        
+        // Check if any new rule/preference entries exist
+        let hasRules = false;
+        for (const line of lines) {
+          try {
+            const entry = JSON.parse(line);
+            if (entry.type === 'rule' || entry.type === 'preference') {
+              hasRules = true;
+              break;
+            }
+          } catch {
+            // Skip invalid JSON
+          }
+        }
+
+        if (hasRules) {
+          info('🔄 New preferences/rules detected, syncing...');
+          await syncRulesCommand({ verbose: false });
+          success('✅ Preferences synced to AI tool configs');
+          console.log('');
+          info('💡 Restart your AI tool to see changes (or it may auto-reload)');
+          console.log('');
+        }
+      } else if (fileName === 'rules.md') {
+        log('Rules file changed manually', verbose);
+        info('📝 Rules file updated');
+        info('💡 Restart your AI tool to see changes');
+        console.log('');
+      }
+    } catch (err) {
+      warn(`Error processing change: ${err instanceof Error ? err.message : 'Unknown error'}`);
+    } finally {
+      isProcessing = false;
+    }
+  });
+
+  preferenceWatcher.on('error', (err: Error) => {
+    error(`Watcher error: ${err.message}`);
+  });
+
+  preferenceWatcher.on('ready', () => {
+    log('Preference watcher ready', verbose);
+    success('✅ Watching for preference changes');
+    console.log('');
+    info('Watching files:');
+    info(`   • ${memoryPath}`);
+    info(`   • ${rulesPath}`);
+    console.log('');
+  });
+
+  // Handle process termination
+  process.on('SIGINT', async () => {
+    console.log('');
+    info('Stopping preference watcher...');
+    if (preferenceWatcher) {
+      await preferenceWatcher.close();
+      preferenceWatcher = null;
+    }
+    success('Preference watcher stopped');
+    process.exit(0);
+  });
+
+  // Keep process alive
+  process.stdin.resume();
+}
+
+/**
+ * Stop the preference watcher
+ */
+export async function stopWatchPreferencesCommand(): Promise<void> {
+  if (preferenceWatcher) {
+    await preferenceWatcher.close();
+    preferenceWatcher = null;
+    success('Preference watcher stopped');
+  } else {
+    info('No preference watcher is running');
+  }
+}
+

package/src/commands/watch.ts

@@ -0,0 +1,239 @@
+/**
+ * MemoryLink - Watch Command
+ * File watcher for real-time protection enforcement
+ */
+
+import * as path from 'path';
+import * as chokidar from 'chokidar';
+import { minimatch } from 'minimatch';
+import {
+  isInitialized,
+  getTimestamp,
+  success,
+  error,
+  warn,
+  info,
+  log,
+  findRoot,
+  readIgnorePatterns,
+  relativePath,
+  getFilePath,
+  appendToFile,
+  appendJsonlEntry,
+  generateId,
+  normalizePathForStorage,
+  checkSecretsBeforeWrite,
+} from '../utils.js';
+import { isFileProtected } from './protect.js';
+import { syncRulesCommand } from './sync-rules.js';
+import type { GlobalOptions, MemoryEntry, ChangeEntry } from '../types.js';
+
+let watcher: chokidar.FSWatcher | null = null;
+
+export async function watchCommand(
+  options: GlobalOptions & { ignore?: string[]; autoLog?: boolean } = {}
+): Promise<void> {
+  const { verbose, ignore: extraIgnore = [], autoLog = true } = options;
+
+  // Check initialization
+  const root = findRoot();
+  if (!root || !isInitialized(root)) {
+    error('MemoryLink is not initialized. Run: memorylink init');
+    process.exit(1);
+  }
+
+  // Get ignore patterns
+  const ignorePatterns = [...readIgnorePatterns(root), ...extraIgnore];
+  
+  log(`Starting watcher in: ${root}`, verbose);
+  log(`Ignore patterns: ${ignorePatterns.length}`, verbose);
+
+  // Stop existing watcher if any
+  if (watcher) {
+    await watcher.close();
+  }
+
+  console.log('');
+  info('🔍 MemoryLink Watcher started');
+  if (autoLog) {
+    info('📝 Auto-logging enabled (file changes → memory.log)');
+  }
+  console.log('');
+  info(`Watching: ${root}`);
+  info(`Ignoring: ${ignorePatterns.length} patterns`);
+  console.log('');
+  console.log('   Press Ctrl+C to stop');
+  console.log('');
+
+  // Create watcher
+  watcher = chokidar.watch(root, {
+    ignored: (filePath: string) => {
+      const relative = relativePath(filePath, root);
+      
+      // Always ignore .memorylink directory for watching (but we still track changes)
+      if (relative.startsWith('.memorylink')) {
+        return true;
+      }
+      
+      // Check ignore patterns
+      return ignorePatterns.some(pattern => {
+        return minimatch(relative, pattern, { dot: true }) ||
+               minimatch(filePath, pattern, { dot: true });
+      });
+    },
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 300,
+      pollInterval: 100,
+    },
+  });
+
+  // Event handlers
+  watcher.on('change', (filePath: string) => {
+    handleFileChange(filePath, 'edited', root, verbose, autoLog);
+  });
+
+  watcher.on('add', (filePath: string) => {
+    handleFileChange(filePath, 'created', root, verbose, autoLog);
+  });
+
+  watcher.on('unlink', (filePath: string) => {
+    handleFileChange(filePath, 'deleted', root, verbose, autoLog);
+  });
+
+  watcher.on('error', (err: Error) => {
+    error(`Watcher error: ${err.message}`);
+  });
+
+  watcher.on('ready', () => {
+    log('Watcher ready', verbose);
+  });
+
+  // Handle process termination
+  process.on('SIGINT', async () => {
+    console.log('');
+    info('Stopping watcher...');
+    if (watcher) {
+      await watcher.close();
+    }
+    process.exit(0);
+  });
+}
+
+async function handleFileChange(
+  filePath: string,
+  action: 'created' | 'edited' | 'deleted',
+  root: string,
+  verbose?: boolean,
+  autoLog?: boolean
+): Promise<void> {
+  const relative = relativePath(filePath, root);
+  const timestamp = getTimestamp();
+
+  log(`File ${action}: ${relative}`, verbose);
+
+  // Normalize path for storage
+  const normalizedFile = normalizePathForStorage(filePath, root);
+
+  // Check if file is protected
+  if (isFileProtected(relative, root)) {
+    console.log('');
+    warn(`⚠️  PROTECTED FILE ${action.toUpperCase()}: ${relative}`);
+    console.log(`   Time: ${timestamp}`);
+    console.log('   This file is in the protected list!');
+    console.log('');
+
+    // Log the violation to changes.log
+    const changesPath = getFilePath('CHANGES', root);
+    const changeEntry: ChangeEntry = {
+      id: generateId(),
+      ts: timestamp,
+      agent: 'watcher',
+      file: normalizedFile,
+      action,
+      reason: `⚠️ PROTECTED FILE ${action.toUpperCase()} (VIOLATION DETECTED)`,
+      status: 'ACTIVE',
+    };
+    await appendJsonlEntry(changesPath, changeEntry);
+  } else {
+    // Log normal changes to changes.log
+    const changesPath = getFilePath('CHANGES', root);
+    const changeEntry: ChangeEntry = {
+      id: generateId(),
+      ts: timestamp,
+      agent: 'watcher',
+      file: normalizedFile,
+      action,
+      reason: `File ${action} by watcher`,
+      status: 'ACTIVE',
+    };
+    await appendJsonlEntry(changesPath, changeEntry);
+
+    // Auto-log to memory.log if enabled (NEW FEATURE)
+    if (autoLog && (action === 'edited' || action === 'created')) {
+      try {
+        // Skip binary files and very large files
+        const stats = require('fs').statSync(filePath);
+        if (stats.size > 1000000) { // Skip files > 1MB
+          log(`Skipping large file: ${relative} (${stats.size} bytes)`, verbose);
+          return;
+        }
+
+        // Try to read file content (skip if binary)
+        let fileContent: string | null = null;
+        try {
+          fileContent = require('fs').readFileSync(filePath, 'utf-8');
+        } catch (e) {
+          // Binary file or read error - skip auto-logging
+          log(`Skipping binary/unreadable file: ${relative}`, verbose);
+          return;
+        }
+
+        // Create memory entry for file change
+        const memoryPath = getFilePath('MEMORY', root);
+        const memoryEntry: MemoryEntry = {
+          id: generateId(),
+          ts: timestamp,
+          type: 'note',
+          details: `File ${action}: ${normalizedFile}. Auto-logged by file watcher at ${timestamp}.`,
+          tags: ['auto-logged', 'file-watcher', action],
+          status: 'ACTIVE',
+          agent: 'watcher',
+        };
+
+        // Check for secrets before writing
+        if (checkSecretsBeforeWrite(memoryEntry.details, false)) {
+          await appendJsonlEntry(memoryPath, memoryEntry);
+          
+          // Auto-sync rules if this is a preference/rule change
+          if (normalizedFile.includes('preferences') || normalizedFile.includes('rules')) {
+            await syncRulesCommand({ verbose });
+          }
+
+          if (verbose) {
+            log(`   ✅ Auto-logged to memory.log: ${relative}`, verbose);
+          }
+        }
+      } catch (err) {
+        // Silently fail auto-logging to not interrupt watcher
+        log(`Failed to auto-log ${relative}: ${err instanceof Error ? err.message : 'Unknown error'}`, verbose);
+      }
+    }
+
+    if (verbose) {
+      console.log(`   \x1b[90m${timestamp}\x1b[0m ${action}: ${relative}`);
+    }
+  }
+}
+
+export async function stopWatchCommand(): Promise<void> {
+  if (watcher) {
+    await watcher.close();
+    watcher = null;
+    success('Watcher stopped');
+  } else {
+    info('No watcher is running');
+  }
+}
+

package/src/config/thresholds.ts

@@ -0,0 +1,14 @@
+export interface FeatureThresholds {
+  treeSitter: number;
+  treeSitterUrgent?: number;
+  dashboard: number;
+  deferIfLow: number;
+}
+
+export const DEFAULT_THRESHOLDS: FeatureThresholds = {
+  treeSitter: 100,
+  treeSitterUrgent: 75,
+  dashboard: 50,
+  deferIfLow: 30,
+};
+

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * MemoryLink - Main Entry Point
+ * Universal memory layer for AI coding assistants
+ */
+
+export * from './types.js';
+export * from './utils.js';
+export * from './commands/index.js';
+
+// Default export for programmatic usage
+export { default as MemoryLink } from './memorylink.js';
+