claude-code-workflow 6.1.4 → 6.2.1

package/src/core/cache-manager.ts

@@ -0,0 +1,294 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { StoragePaths, ensureStorageDir } from '../config/storage-paths.js';
+
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  fileHashes: Map<string, number>; // file path -> mtime
+  ttl?: number;
+}
+
+interface CacheOptions {
+  ttl?: number; // Time-to-live in milliseconds (default: 5 minutes)
+  cacheDir?: string; // Cache directory (default: .ccw-cache)
+}
+
+/**
+ * CacheManager class for storing and retrieving dashboard data
+ * Tracks file modification times to detect changes and invalidate cache
+ */
+export class CacheManager<T> {
+  private cacheFile: string;
+  private ttl: number;
+  private cacheDir: string;
+
+  /**
+   * Create a new CacheManager instance
+   * @param cacheKey - Unique identifier for this cache (e.g., 'dashboard-data')
+   * @param options - Cache configuration options
+   */
+  constructor(cacheKey: string, options: CacheOptions = {}) {
+    if (!options.cacheDir) {
+      throw new Error('CacheManager requires cacheDir option. Use StoragePaths.project(path).cache');
+    }
+    this.ttl = options.ttl || 5 * 60 * 1000; // Default: 5 minutes
+    this.cacheDir = options.cacheDir;
+    this.cacheFile = join(this.cacheDir, `${cacheKey}.json`);
+  }
+
+  /**
+   * Get cached data if valid, otherwise return null
+   * @param watchPaths - Array of file/directory paths to check for modifications
+   * @returns Cached data or null if invalid/expired
+   */
+  get(watchPaths: string[] = []): T | null {
+    if (!existsSync(this.cacheFile)) {
+      return null;
+    }
+
+    try {
+      const content = readFileSync(this.cacheFile, 'utf8');
+      const entry: CacheEntry<T> = JSON.parse(content, (key, value) => {
+        // Revive Map objects from JSON
+        if (key === 'fileHashes' && value && typeof value === 'object') {
+          return new Map(Object.entries(value));
+        }
+        return value;
+      });
+
+      // Check TTL expiration
+      if (this.ttl > 0) {
+        const age = Date.now() - entry.timestamp;
+        if (age > this.ttl) {
+          return null;
+        }
+      }
+
+      // Check if any watched files have changed
+      if (watchPaths.length > 0) {
+        const currentHashes = this.computeFileHashes(watchPaths);
+        if (!this.hashesMatch(entry.fileHashes, currentHashes)) {
+          return null;
+        }
+      }
+
+      return entry.data;
+    } catch (err) {
+      // If cache file is corrupted or unreadable, treat as invalid
+      console.warn(`Cache read error for ${this.cacheFile}:`, (err as Error).message);
+      return null;
+    }
+  }
+
+  /**
+   * Store data in cache with current timestamp and file hashes
+   * @param data - Data to cache
+   * @param watchPaths - Array of file/directory paths to track
+   */
+  set(data: T, watchPaths: string[] = []): void {
+    try {
+      // Ensure cache directory exists
+      if (!existsSync(this.cacheDir)) {
+        mkdirSync(this.cacheDir, { recursive: true });
+      }
+
+      const entry: CacheEntry<T> = {
+        data,
+        timestamp: Date.now(),
+        fileHashes: this.computeFileHashes(watchPaths),
+        ttl: this.ttl
+      };
+
+      // Convert Map to plain object for JSON serialization
+      const serializable = {
+        ...entry,
+        fileHashes: Object.fromEntries(entry.fileHashes)
+      };
+
+      writeFileSync(this.cacheFile, JSON.stringify(serializable, null, 2), 'utf8');
+    } catch (err) {
+      console.warn(`Cache write error for ${this.cacheFile}:`, (err as Error).message);
+    }
+  }
+
+  /**
+   * Invalidate (delete) the cache
+   */
+  invalidate(): void {
+    try {
+      if (existsSync(this.cacheFile)) {
+        const fs = require('fs');
+        fs.unlinkSync(this.cacheFile);
+      }
+    } catch (err) {
+      console.warn(`Cache invalidation error for ${this.cacheFile}:`, (err as Error).message);
+    }
+  }
+
+  /**
+   * Check if cache is valid without retrieving data
+   * @param watchPaths - Array of file/directory paths to check
+   * @returns True if cache exists and is valid
+   */
+  isValid(watchPaths: string[] = []): boolean {
+    return this.get(watchPaths) !== null;
+  }
+
+  /**
+   * Compute file modification times for all watched paths
+   * @param watchPaths - Array of file/directory paths
+   * @returns Map of path to mtime
+   */
+  private computeFileHashes(watchPaths: string[]): Map<string, number> {
+    const hashes = new Map<string, number>();
+
+    for (const path of watchPaths) {
+      try {
+        if (!existsSync(path)) {
+          continue;
+        }
+
+        const stats = statSync(path);
+
+        if (stats.isDirectory()) {
+          // For directories, use directory mtime (detects file additions/deletions)
+          hashes.set(path, stats.mtimeMs);
+
+          // Also recursively scan for workflow session files
+          this.scanDirectory(path, hashes);
+        } else {
+          // For files, use file mtime
+          hashes.set(path, stats.mtimeMs);
+        }
+      } catch (err) {
+        // Skip paths that can't be accessed
+        console.warn(`Cannot access path ${path}:`, (err as Error).message);
+      }
+    }
+
+    return hashes;
+  }
+
+  /**
+   * Recursively scan directory for important files
+   * @param dirPath - Directory to scan
+   * @param hashes - Map to store file hashes
+   * @param depth - Current recursion depth (max 3)
+   */
+  private scanDirectory(dirPath: string, hashes: Map<string, number>, depth: number = 0): void {
+    if (depth > 3) return; // Limit recursion depth
+
+    try {
+      const fs = require('fs');
+      const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = join(dirPath, entry.name);
+
+        if (entry.isDirectory()) {
+          // Track important directories
+          if (entry.name === '.task' || entry.name === '.review' || entry.name === '.summaries') {
+            const stats = statSync(fullPath);
+            hashes.set(fullPath, stats.mtimeMs);
+            this.scanDirectory(fullPath, hashes, depth + 1);
+          } else if (entry.name.startsWith('WFS-')) {
+            // Scan WFS session directories
+            const stats = statSync(fullPath);
+            hashes.set(fullPath, stats.mtimeMs);
+            this.scanDirectory(fullPath, hashes, depth + 1);
+          }
+        } else if (entry.isFile()) {
+          // Track important files
+          if (
+            entry.name.endsWith('.json') ||
+            entry.name === 'IMPL_PLAN.md' ||
+            entry.name === 'TODO_LIST.md' ||
+            entry.name === 'workflow-session.json'
+          ) {
+            const stats = statSync(fullPath);
+            hashes.set(fullPath, stats.mtimeMs);
+          }
+        }
+      }
+    } catch (err) {
+      // Skip directories that can't be read
+      console.warn(`Cannot scan directory ${dirPath}:`, (err as Error).message);
+    }
+  }
+
+  /**
+   * Compare two file hash maps
+   * @param oldHashes - Previous hashes
+   * @param newHashes - Current hashes
+   * @returns True if hashes match (no changes)
+   */
+  private hashesMatch(oldHashes: Map<string, number>, newHashes: Map<string, number>): boolean {
+    // Check if any files were added or removed
+    if (oldHashes.size !== newHashes.size) {
+      return false;
+    }
+
+    // Check if any file mtimes changed
+    const entries = Array.from(oldHashes.entries());
+    for (let i = 0; i < entries.length; i++) {
+      const path = entries[i][0];
+      const oldMtime = entries[i][1];
+      const newMtime = newHashes.get(path);
+      if (newMtime === undefined || newMtime !== oldMtime) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get cache statistics
+   * @returns Cache info object
+   */
+  getStats(): { exists: boolean; age?: number; fileCount?: number; size?: number } {
+    if (!existsSync(this.cacheFile)) {
+      return { exists: false };
+    }
+
+    try {
+      const stats = statSync(this.cacheFile);
+      const content = readFileSync(this.cacheFile, 'utf8');
+      const entry = JSON.parse(content);
+
+      return {
+        exists: true,
+        age: Date.now() - entry.timestamp,
+        fileCount: Object.keys(entry.fileHashes || {}).length,
+        size: stats.size
+      };
+    } catch {
+      return { exists: false };
+    }
+  }
+}
+
+/**
+ * Extract project path from workflow directory
+ * @param workflowDir - Path to .workflow directory (e.g., /project/.workflow)
+ * @returns Project root path
+ */
+function extractProjectPath(workflowDir: string): string {
+  // workflowDir is typically {projectPath}/.workflow
+  return workflowDir.replace(/[\/\\]\.workflow$/, '') || workflowDir;
+}
+
+/**
+ * Create a cache manager for dashboard data
+ * @param workflowDir - Path to .workflow directory
+ * @param ttl - Optional TTL in milliseconds
+ * @returns CacheManager instance
+ */
+export function createDashboardCache(workflowDir: string, ttl?: number): CacheManager<any> {
+  // Use centralized storage path
+  const projectPath = extractProjectPath(workflowDir);
+  const cacheDir = StoragePaths.project(projectPath).cache;
+  ensureStorageDir(cacheDir);
+  return new CacheManager('dashboard-data', { cacheDir, ttl });
+}

package/src/core/claude-freshness.ts

@@ -0,0 +1,319 @@
+/**
+ * CLAUDE.md Freshness Calculator
+ * Calculates freshness scores based on git changes since last update
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, statSync, readdirSync } from 'fs';
+import { dirname, extname, relative, join } from 'path';
+import { getCoreMemoryStore, ClaudeUpdateRecord } from './core-memory-store.js';
+
+// Source file extensions to track (from detect-changed-modules.ts)
+const SOURCE_EXTENSIONS = [
+  '.md', '.js', '.ts', '.jsx', '.tsx',
+  '.py', '.go', '.rs', '.java', '.cpp', '.c', '.h',
+  '.sh', '.ps1', '.json', '.yaml', '.yml'
+];
+
+// Directories to exclude
+const EXCLUDE_DIRS = [
+  '.git', '__pycache__', 'node_modules', '.venv', 'venv', 'env',
+  'dist', 'build', '.cache', '.pytest_cache', '.mypy_cache',
+  'coverage', '.nyc_output', 'logs', 'tmp', 'temp', '.ccw', '.workflow'
+];
+
+export interface FreshnessResult {
+  path: string;
+  level: 'user' | 'project' | 'module';
+  relativePath: string;
+  parentDirectory?: string;
+  lastUpdated: string | null;
+  lastModified: string;
+  changedFilesCount: number;
+  freshness: number;
+  updateSource?: string;
+  needsUpdate: boolean;
+  changedFiles?: string[];
+}
+
+export interface FreshnessSummary {
+  totalFiles: number;
+  staleCount: number;
+  averageFreshness: number;
+  lastScanAt: string;
+}
+
+export interface FreshnessResponse {
+  files: FreshnessResult[];
+  summary: FreshnessSummary;
+}
+
+/**
+ * Check if git is available and we're in a repo
+ */
+function isGitRepo(basePath: string): boolean {
+  try {
+    execSync('git rev-parse --git-dir', { cwd: basePath, stdio: 'pipe' });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Get current git commit hash
+ */
+export function getCurrentGitCommit(basePath: string): string | null {
+  try {
+    const output = execSync('git rev-parse HEAD', {
+      cwd: basePath,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    return output || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Get files changed since a specific date within a directory
+ */
+function getChangedFilesSince(basePath: string, modulePath: string, sinceDate: string): string[] {
+  try {
+    // Format date for git
+    const date = new Date(sinceDate);
+    const formattedDate = date.toISOString().split('T')[0];
+
+    // Get files changed since the date
+    const output = execSync(
+      `git log --name-only --since="${formattedDate}" --pretty=format: -- "${modulePath}"`,
+      {
+        cwd: basePath,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      }
+    ).trim();
+
+    if (!output) return [];
+
+    // Get unique files and filter by source extensions
+    const files = [...new Set(output.split('\n').filter(f => f.trim()))];
+    return files.filter(f => {
+      const ext = extname(f).toLowerCase();
+      return SOURCE_EXTENSIONS.includes(ext);
+    });
+  } catch (e) {
+    // Fallback to mtime-based detection
+    return findFilesModifiedSince(modulePath, sinceDate);
+  }
+}
+
+/**
+ * Fallback: Find files modified since a date using mtime
+ */
+function findFilesModifiedSince(dirPath: string, sinceDate: string): string[] {
+  const results: string[] = [];
+  const cutoffTime = new Date(sinceDate).getTime();
+
+  function scan(currentPath: string): void {
+    try {
+      const entries = readdirSync(currentPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          if (EXCLUDE_DIRS.includes(entry.name)) continue;
+          scan(join(currentPath, entry.name));
+        } else if (entry.isFile()) {
+          const ext = extname(entry.name).toLowerCase();
+          if (!SOURCE_EXTENSIONS.includes(ext)) continue;
+
+          const fullPath = join(currentPath, entry.name);
+          try {
+            const stat = statSync(fullPath);
+            if (stat.mtimeMs > cutoffTime) {
+              results.push(relative(dirPath, fullPath));
+            }
+          } catch (e) {
+            // Skip files we can't stat
+          }
+        }
+      }
+    } catch (e) {
+      // Ignore permission errors
+    }
+  }
+
+  if (existsSync(dirPath)) {
+    scan(dirPath);
+  }
+  return results;
+}
+
+/**
+ * Calculate freshness for a single CLAUDE.md file
+ */
+export function calculateFreshness(
+  filePath: string,
+  fileLevel: 'user' | 'project' | 'module',
+  lastUpdateTime: string | null,
+  lastModified: string,
+  projectPath: string,
+  threshold: number = 20
+): FreshnessResult {
+  // Use lastUpdateTime from history, or fall back to file mtime
+  const effectiveUpdateTime = lastUpdateTime || lastModified;
+
+  // Calculate module path for change detection
+  let modulePath: string | null = null;
+  let changedFiles: string[] = [];
+
+  if (fileLevel === 'module') {
+    // For module-level files, scan the parent directory
+    modulePath = dirname(filePath);
+  } else if (fileLevel === 'project') {
+    // For project-level files, scan the project root
+    modulePath = projectPath;
+  }
+
+  // Only calculate changes for module/project level in git repos
+  if (modulePath && isGitRepo(projectPath)) {
+    changedFiles = getChangedFilesSince(projectPath, modulePath, effectiveUpdateTime);
+    // Exclude the CLAUDE.md file itself
+    changedFiles = changedFiles.filter(f => !f.endsWith('CLAUDE.md'));
+  }
+
+  // Calculate freshness percentage
+  const changedCount = changedFiles.length;
+  const freshness = Math.max(0, 100 - Math.floor((changedCount / threshold) * 100));
+
+  // Determine parent directory for display
+  const parentDirectory = fileLevel === 'module'
+    ? filePath.split(/[\\/]/).slice(-2, -1)[0]
+    : undefined;
+
+  return {
+    path: filePath,
+    level: fileLevel,
+    relativePath: relative(projectPath, filePath).replace(/\\/g, '/'),
+    parentDirectory,
+    lastUpdated: lastUpdateTime,
+    lastModified,
+    changedFilesCount: changedCount,
+    freshness,
+    needsUpdate: freshness < 50,
+    changedFiles: changedFiles.slice(0, 20) // Limit to first 20 for detail view
+  };
+}
+
+/**
+ * Calculate freshness for all CLAUDE.md files in a project
+ */
+export function calculateAllFreshness(
+  claudeFiles: Array<{
+    path: string;
+    level: 'user' | 'project' | 'module';
+    lastModified: string;
+  }>,
+  projectPath: string,
+  threshold: number = 20
+): FreshnessResponse {
+  // Get update records from store
+  const store = getCoreMemoryStore(projectPath);
+  const updateRecords = store.getAllClaudeUpdateRecords();
+
+  // Create a map for quick lookup
+  const updateMap = new Map<string, ClaudeUpdateRecord>();
+  for (const record of updateRecords) {
+    updateMap.set(record.file_path, record);
+  }
+
+  const results: FreshnessResult[] = [];
+
+  for (const file of claudeFiles) {
+    const updateRecord = updateMap.get(file.path);
+
+    const result = calculateFreshness(
+      file.path,
+      file.level,
+      updateRecord?.updated_at || null,
+      file.lastModified,
+      projectPath,
+      threshold
+    );
+
+    if (updateRecord) {
+      result.updateSource = updateRecord.update_source;
+    }
+
+    results.push(result);
+  }
+
+  // Calculate summary
+  const staleCount = results.filter(r => r.needsUpdate).length;
+  const totalFreshness = results.reduce((sum, r) => sum + r.freshness, 0);
+  const averageFreshness = results.length > 0 ? Math.round(totalFreshness / results.length) : 100;
+
+  return {
+    files: results,
+    summary: {
+      totalFiles: results.length,
+      staleCount,
+      averageFreshness,
+      lastScanAt: new Date().toISOString()
+    }
+  };
+}
+
+/**
+ * Mark a CLAUDE.md file as updated
+ */
+export function markFileAsUpdated(
+  filePath: string,
+  fileLevel: 'user' | 'project' | 'module',
+  updateSource: 'manual' | 'cli_sync' | 'dashboard' | 'api',
+  projectPath: string,
+  metadata?: object
+): ClaudeUpdateRecord {
+  const store = getCoreMemoryStore(projectPath);
+  const now = new Date().toISOString();
+
+  // Get current git commit
+  const gitCommit = getCurrentGitCommit(projectPath);
+
+  // Calculate changed files count before this update
+  const lastUpdate = store.getLastClaudeUpdate(filePath);
+  let filesChangedCount = 0;
+
+  if (lastUpdate && isGitRepo(projectPath)) {
+    const modulePath = fileLevel === 'module' ? dirname(filePath) : projectPath;
+    const changedFiles = getChangedFilesSince(projectPath, modulePath, lastUpdate.updated_at);
+    filesChangedCount = changedFiles.filter(f => !f.endsWith('CLAUDE.md')).length;
+  }
+
+  // Insert update record
+  const record = store.insertClaudeUpdateRecord({
+    file_path: filePath,
+    file_level: fileLevel,
+    module_path: fileLevel === 'module' ? dirname(filePath) : undefined,
+    updated_at: now,
+    update_source: updateSource,
+    git_commit_hash: gitCommit || undefined,
+    files_changed_before_update: filesChangedCount,
+    metadata: metadata ? JSON.stringify(metadata) : undefined
+  });
+
+  return record;
+}
+
+/**
+ * Get update history for a file
+ */
+export function getUpdateHistory(
+  filePath: string,
+  projectPath: string,
+  limit: number = 50
+): ClaudeUpdateRecord[] {
+  const store = getCoreMemoryStore(projectPath);
+  return store.getClaudeUpdateHistory(filePath, limit);
+}