claude-code-workflow 6.1.3 → 6.2.1

package/src/core/routes/help-routes.ts

@@ -0,0 +1,308 @@
+// @ts-nocheck
+/**
+ * Help Routes Module
+ * Handles all Help-related API endpoints for command guide and CodexLens docs
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import { readFileSync, existsSync, watch } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export interface RouteContext {
+  pathname: string;
+  url: URL;
+  req: IncomingMessage;
+  res: ServerResponse;
+  initialPath: string;
+  handlePostRequest: (req: IncomingMessage, res: ServerResponse, handler: (body: unknown) => Promise<any>) => void;
+  broadcastToClients: (data: unknown) => void;
+}
+
+// ========== In-Memory Cache ==========
+interface CacheEntry {
+  data: any;
+  timestamp: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+const CACHE_TTL = 300000; // 5 minutes
+
+/**
+ * Get cached data or load from file
+ */
+function getCachedData(key: string, filePath: string): any {
+  const now = Date.now();
+  const cached = cache.get(key);
+
+  // Return cached data if valid
+  if (cached && (now - cached.timestamp) < CACHE_TTL) {
+    return cached.data;
+  }
+
+  // Load fresh data
+  try {
+    if (!existsSync(filePath)) {
+      console.error(`Help data file not found: ${filePath}`);
+      return null;
+    }
+
+    const content = readFileSync(filePath, 'utf8');
+    const data = JSON.parse(content);
+
+    // Update cache
+    cache.set(key, { data, timestamp: now });
+
+    return data;
+  } catch (error) {
+    console.error(`Failed to load help data from ${filePath}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Invalidate cache for a specific key
+ */
+function invalidateCache(key: string): void {
+  cache.delete(key);
+  console.log(`Cache invalidated: ${key}`);
+}
+
+// ========== File Watchers ==========
+let watchersInitialized = false;
+
+/**
+ * Initialize file watchers for JSON indexes
+ */
+function initializeFileWatchers(): void {
+  if (watchersInitialized) return;
+
+  const indexDir = join(homedir(), '.claude', 'skills', 'command-guide', 'index');
+
+  if (!existsSync(indexDir)) {
+    console.warn(`Command guide index directory not found: ${indexDir}`);
+    return;
+  }
+
+  try {
+    // Watch all JSON files in index directory
+    const watcher = watch(indexDir, { recursive: false }, (eventType, filename) => {
+      if (!filename || !filename.endsWith('.json')) return;
+
+      console.log(`File change detected: ${filename} (${eventType})`);
+
+      // Invalidate relevant cache entries
+      if (filename === 'all-commands.json') {
+        invalidateCache('all-commands');
+      } else if (filename === 'command-relationships.json') {
+        invalidateCache('command-relationships');
+      } else if (filename === 'by-category.json') {
+        invalidateCache('by-category');
+      }
+    });
+
+    watchersInitialized = true;
+    console.log(`File watchers initialized for: ${indexDir}`);
+  } catch (error) {
+    console.error('Failed to initialize file watchers:', error);
+  }
+}
+
+// ========== Helper Functions ==========
+
+/**
+ * Filter commands by search query
+ */
+function filterCommands(commands: any[], query: string): any[] {
+  if (!query) return commands;
+
+  const lowerQuery = query.toLowerCase();
+  return commands.filter(cmd =>
+    cmd.name?.toLowerCase().includes(lowerQuery) ||
+    cmd.command?.toLowerCase().includes(lowerQuery) ||
+    cmd.description?.toLowerCase().includes(lowerQuery) ||
+    cmd.category?.toLowerCase().includes(lowerQuery)
+  );
+}
+
+/**
+ * Group commands by category with subcategories
+ */
+function groupCommandsByCategory(commands: any[]): any {
+  const grouped: any = {};
+
+  for (const cmd of commands) {
+    const category = cmd.category || 'general';
+    const subcategory = cmd.subcategory || null;
+
+    if (!grouped[category]) {
+      grouped[category] = {
+        name: category,
+        commands: [],
+        subcategories: {}
+      };
+    }
+
+    if (subcategory) {
+      if (!grouped[category].subcategories[subcategory]) {
+        grouped[category].subcategories[subcategory] = [];
+      }
+      grouped[category].subcategories[subcategory].push(cmd);
+    } else {
+      grouped[category].commands.push(cmd);
+    }
+  }
+
+  return grouped;
+}
+
+// ========== API Routes ==========
+
+/**
+ * Handle Help routes
+ * @returns true if route was handled, false otherwise
+ */
+export async function handleHelpRoutes(ctx: RouteContext): Promise<boolean> {
+  const { pathname, url, req, res } = ctx;
+
+  // Initialize file watchers on first request
+  initializeFileWatchers();
+
+  const indexDir = join(homedir(), '.claude', 'skills', 'command-guide', 'index');
+
+  // API: Get all commands with optional search
+  if (pathname === '/api/help/commands') {
+    const searchQuery = url.searchParams.get('q') || '';
+    const filePath = join(indexDir, 'all-commands.json');
+
+    let commands = getCachedData('all-commands', filePath);
+
+    if (!commands) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Commands data not found' }));
+      return true;
+    }
+
+    // Filter by search query if provided
+    if (searchQuery) {
+      commands = filterCommands(commands, searchQuery);
+    }
+
+    // Group by category
+    const grouped = groupCommandsByCategory(commands);
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      commands: commands,
+      grouped: grouped,
+      total: commands.length
+    }));
+    return true;
+  }
+
+  // API: Get workflow command relationships
+  if (pathname === '/api/help/workflows') {
+    const filePath = join(indexDir, 'command-relationships.json');
+    const relationships = getCachedData('command-relationships', filePath);
+
+    if (!relationships) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Workflow relationships not found' }));
+      return true;
+    }
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(relationships));
+    return true;
+  }
+
+  // API: Get commands by category
+  if (pathname === '/api/help/commands/by-category') {
+    const filePath = join(indexDir, 'by-category.json');
+    const byCategory = getCachedData('by-category', filePath);
+
+    if (!byCategory) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Category data not found' }));
+      return true;
+    }
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(byCategory));
+    return true;
+  }
+
+  // API: Get CodexLens documentation metadata
+  if (pathname === '/api/help/codexlens') {
+    // Return CodexLens quick-start guide data
+    const codexLensData = {
+      title: 'CodexLens Quick Start',
+      description: 'Fast code indexing and semantic search for large codebases',
+      sections: [
+        {
+          title: 'Key Concepts',
+          items: [
+            {
+              name: 'Indexing',
+              description: 'CodexLens builds a semantic index of your codebase for fast retrieval',
+              command: 'codex_lens(action="init", path=".")'
+            },
+            {
+              name: 'Search Modes',
+              description: 'Text search for exact matches, semantic search for concept-based queries',
+              command: 'codex_lens(action="search", query="authentication logic", mode="semantic")'
+            },
+            {
+              name: 'Symbol Navigation',
+              description: 'Extract and navigate code symbols (functions, classes, interfaces)',
+              command: 'codex_lens(action="symbol", file="path/to/file.py")'
+            }
+          ]
+        },
+        {
+          title: 'Common Commands',
+          items: [
+            {
+              name: 'Initialize Index',
+              command: 'codex_lens(action="init", path=".")',
+              description: 'Index the current directory'
+            },
+            {
+              name: 'Text Search',
+              command: 'codex_lens(action="search", query="function name", path=".")',
+              description: 'Search for exact text matches'
+            },
+            {
+              name: 'Semantic Search',
+              command: 'codex_lens(action="search", query="user authentication", mode="semantic")',
+              description: 'Search by concept or meaning'
+            },
+            {
+              name: 'Check Status',
+              command: 'codex_lens(action="status")',
+              description: 'View indexing status for all projects'
+            }
+          ]
+        },
+        {
+          title: 'Best Practices',
+          items: [
+            { description: 'Index large codebases (>500 files) for optimal performance' },
+            { description: 'Use semantic search for exploratory tasks' },
+            { description: 'Combine with smart_search for medium-sized projects' },
+            { description: 'Re-index after major code changes'  }
+          ]
+        }
+      ],
+      links: [
+        { text: 'Full Documentation', url: 'https://github.com/yourusername/codex-lens' },
+        { text: 'Tool Selection Guide', url: '/.claude/rules/tool-selection.md' }
+      ]
+    };
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(codexLensData));
+    return true;
+  }
+
+  return false;
+}

package/src/core/routes/hooks-routes.ts

@@ -0,0 +1,405 @@
+// @ts-nocheck
+/**
+ * Hooks Routes Module
+ * Handles all hooks-related API endpoints
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+
+export interface RouteContext {
+  pathname: string;
+  url: URL;
+  req: IncomingMessage;
+  res: ServerResponse;
+  initialPath: string;
+  handlePostRequest: (req: IncomingMessage, res: ServerResponse, handler: (body: unknown) => Promise<any>) => void;
+  broadcastToClients: (data: unknown) => void;
+  extractSessionIdFromPath: (filePath: string) => string | null;
+}
+
+// ========================================
+// Helper Functions
+// ========================================
+
+const GLOBAL_SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
+
+/**
+ * Get project settings path
+ * @param {string} projectPath
+ * @returns {string}
+ */
+function getProjectSettingsPath(projectPath) {
+  const normalizedPath = projectPath.replace(/\//g, '\\').replace(/^\\([a-zA-Z])\\/, '$1:\\');
+  return join(normalizedPath, '.claude', 'settings.json');
+}
+
+/**
+ * Read settings file safely
+ * @param {string} filePath
+ * @returns {Object}
+ */
+function readSettingsFile(filePath) {
+  try {
+    if (!existsSync(filePath)) {
+      return {};
+    }
+    const content = readFileSync(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch (error: unknown) {
+    console.error(`Error reading settings file ${filePath}:`, error);
+    return {};
+  }
+}
+
+/**
+ * Get hooks configuration from global and project settings
+ * @param {string} projectPath
+ * @returns {Object}
+ */
+function getHooksConfig(projectPath) {
+  const globalSettings = readSettingsFile(GLOBAL_SETTINGS_PATH);
+  const projectSettingsPath = projectPath ? getProjectSettingsPath(projectPath) : null;
+  const projectSettings = projectSettingsPath ? readSettingsFile(projectSettingsPath) : {};
+
+  return {
+    global: {
+      path: GLOBAL_SETTINGS_PATH,
+      hooks: globalSettings.hooks || {}
+    },
+    project: {
+      path: projectSettingsPath,
+      hooks: projectSettings.hooks || {}
+    }
+  };
+}
+
+/**
+ * Save a hook to settings file
+ * @param {string} projectPath
+ * @param {string} scope - 'global' or 'project'
+ * @param {string} event - Hook event type
+ * @param {Object} hookData - Hook configuration
+ * @returns {Object}
+ */
+function saveHookToSettings(projectPath, scope, event, hookData) {
+  try {
+    const filePath = scope === 'global' ? GLOBAL_SETTINGS_PATH : getProjectSettingsPath(projectPath);
+    const settings = readSettingsFile(filePath);
+
+    // Ensure hooks object exists
+    if (!settings.hooks) {
+      settings.hooks = {};
+    }
+
+    // Ensure the event array exists
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = [];
+    }
+
+    // Ensure it's an array
+    if (!Array.isArray(settings.hooks[event])) {
+      settings.hooks[event] = [settings.hooks[event]];
+    }
+
+    // Check if we're replacing an existing hook
+    if (hookData.replaceIndex !== undefined) {
+      const index = hookData.replaceIndex;
+      delete hookData.replaceIndex;
+      if (index >= 0 && index < settings.hooks[event].length) {
+        settings.hooks[event][index] = hookData;
+      }
+    } else {
+      // Add new hook
+      settings.hooks[event].push(hookData);
+    }
+
+    // Ensure directory exists and write file
+    const dirPath = dirname(filePath);
+    if (!existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true });
+    }
+    writeFileSync(filePath, JSON.stringify(settings, null, 2), 'utf8');
+
+    return {
+      success: true,
+      event,
+      hookData
+    };
+  } catch (error: unknown) {
+    console.error('Error saving hook:', error);
+    return { error: (error as Error).message };
+  }
+}
+
+/**
+ * Delete a hook from settings file
+ * @param {string} projectPath
+ * @param {string} scope - 'global' or 'project'
+ * @param {string} event - Hook event type
+ * @param {number} hookIndex - Index of hook to delete
+ * @returns {Object}
+ */
+function deleteHookFromSettings(projectPath, scope, event, hookIndex) {
+  try {
+    const filePath = scope === 'global' ? GLOBAL_SETTINGS_PATH : getProjectSettingsPath(projectPath);
+    const settings = readSettingsFile(filePath);
+
+    if (!settings.hooks || !settings.hooks[event]) {
+      return { error: 'Hook not found' };
+    }
+
+    // Ensure it's an array
+    if (!Array.isArray(settings.hooks[event])) {
+      settings.hooks[event] = [settings.hooks[event]];
+    }
+
+    if (hookIndex < 0 || hookIndex >= settings.hooks[event].length) {
+      return { error: 'Invalid hook index' };
+    }
+
+    // Remove the hook
+    settings.hooks[event].splice(hookIndex, 1);
+
+    // Remove empty event arrays
+    if (settings.hooks[event].length === 0) {
+      delete settings.hooks[event];
+    }
+
+    writeFileSync(filePath, JSON.stringify(settings, null, 2), 'utf8');
+
+    return {
+      success: true,
+      event,
+      hookIndex
+    };
+  } catch (error: unknown) {
+    console.error('Error deleting hook:', error);
+    return { error: (error as Error).message };
+  }
+}
+
+// ========================================
+// Session State Tracking (for progressive disclosure)
+// ========================================
+
+// Track sessions that have received startup context
+// Key: sessionId, Value: timestamp of first context load
+const sessionContextState = new Map<string, {
+  firstLoad: string;
+  loadCount: number;
+  lastPrompt?: string;
+}>();
+
+// Cleanup old sessions (older than 24 hours)
+function cleanupOldSessions() {
+  const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+  for (const [sessionId, state] of sessionContextState.entries()) {
+    if (new Date(state.firstLoad).getTime() < cutoff) {
+      sessionContextState.delete(sessionId);
+    }
+  }
+}
+
+// Run cleanup every hour
+setInterval(cleanupOldSessions, 60 * 60 * 1000);
+
+// ========================================
+// Route Handler
+// ========================================
+
+/**
+ * Handle hooks routes
+ * @returns true if route was handled, false otherwise
+ */
+export async function handleHooksRoutes(ctx: RouteContext): Promise<boolean> {
+  const { pathname, url, req, res, initialPath, handlePostRequest, broadcastToClients, extractSessionIdFromPath } = ctx;
+
+  // API: Hook endpoint for Claude Code notifications
+  if (pathname === '/api/hook' && req.method === 'POST') {
+    handlePostRequest(req, res, async (body) => {
+      const { type, filePath, sessionId, ...extraData } = body;
+
+      // Determine session ID from file path if not provided
+      let resolvedSessionId = sessionId;
+      if (!resolvedSessionId && filePath) {
+        resolvedSessionId = extractSessionIdFromPath(filePath);
+      }
+
+      // Handle context hooks (session-start, context)
+      if (type === 'session-start' || type === 'context') {
+        try {
+          const projectPath = url.searchParams.get('path') || initialPath;
+          const { SessionClusteringService } = await import('../session-clustering-service.js');
+          const clusteringService = new SessionClusteringService(projectPath);
+
+          const format = url.searchParams.get('format') || 'markdown';
+
+          // Pass type and prompt to getProgressiveIndex
+          // session-start: returns recent sessions by time
+          // context: returns intent-matched sessions based on prompt
+          const index = await clusteringService.getProgressiveIndex({
+            type: type as 'session-start' | 'context',
+            sessionId: resolvedSessionId,
+            prompt: extraData.prompt // Pass user prompt for intent matching
+          });
+
+          // Return context directly
+          return {
+            success: true,
+            type: 'context',
+            format,
+            content: index,
+            sessionId: resolvedSessionId
+          };
+        } catch (error) {
+          console.error('[Hooks] Failed to generate context:', error);
+          // Return empty content on failure (fail silently)
+          return {
+            success: true,
+            type: 'context',
+            format: 'markdown',
+            content: '',
+            sessionId: resolvedSessionId,
+            error: (error as Error).message
+          };
+        }
+      }
+
+      // Broadcast to all connected WebSocket clients
+      const notification = {
+        type: type || 'session_updated',
+        payload: {
+          sessionId: resolvedSessionId,
+          filePath: filePath,
+          timestamp: new Date().toISOString(),
+          ...extraData  // Pass through toolName, status, result, params, error, etc.
+        }
+      };
+
+      broadcastToClients(notification);
+
+      return { success: true, notification };
+    });
+    return true;
+  }
+
+  // API: Unified Session Context endpoint (Progressive Disclosure)
+  // Automatically detects first prompt vs subsequent prompts
+  // - First prompt: returns cluster-based session overview
+  // - Subsequent prompts: returns intent-matched sessions based on prompt
+  if (pathname === '/api/hook/session-context' && req.method === 'POST') {
+    handlePostRequest(req, res, async (body) => {
+      const { sessionId, prompt } = body as { sessionId?: string; prompt?: string };
+
+      if (!sessionId) {
+        return {
+          success: true,
+          content: '',
+          error: 'sessionId is required'
+        };
+      }
+
+      try {
+        const projectPath = url.searchParams.get('path') || initialPath;
+        const { SessionClusteringService } = await import('../session-clustering-service.js');
+        const clusteringService = new SessionClusteringService(projectPath);
+
+        // Check if this is the first prompt for this session
+        const existingState = sessionContextState.get(sessionId);
+        const isFirstPrompt = !existingState;
+
+        // Update session state
+        if (isFirstPrompt) {
+          sessionContextState.set(sessionId, {
+            firstLoad: new Date().toISOString(),
+            loadCount: 1,
+            lastPrompt: prompt
+          });
+        } else {
+          existingState.loadCount++;
+          existingState.lastPrompt = prompt;
+        }
+
+        // Determine which type of context to return
+        let contextType: 'session-start' | 'context';
+        let content: string;
+
+        if (isFirstPrompt) {
+          // First prompt: return session overview with clusters
+          contextType = 'session-start';
+          content = await clusteringService.getProgressiveIndex({
+            type: 'session-start',
+            sessionId
+          });
+        } else if (prompt && prompt.trim().length > 0) {
+          // Subsequent prompts with content: return intent-matched sessions
+          contextType = 'context';
+          content = await clusteringService.getProgressiveIndex({
+            type: 'context',
+            sessionId,
+            prompt
+          });
+        } else {
+          // Subsequent prompts without content: return minimal context
+          contextType = 'context';
+          content = ''; // No context needed for empty prompts
+        }
+
+        return {
+          success: true,
+          type: contextType,
+          isFirstPrompt,
+          loadCount: sessionContextState.get(sessionId)?.loadCount || 1,
+          content,
+          sessionId
+        };
+      } catch (error) {
+        console.error('[Hooks] Failed to generate session context:', error);
+        return {
+          success: true,
+          content: '',
+          sessionId,
+          error: (error as Error).message
+        };
+      }
+    });
+    return true;
+  }
+
+  // API: Get hooks configuration
+  if (pathname === '/api/hooks' && req.method === 'GET') {
+    const projectPathParam = url.searchParams.get('path');
+    const hooksData = getHooksConfig(projectPathParam);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(hooksData));
+    return true;
+  }
+
+  // API: Save hook
+  if (pathname === '/api/hooks' && req.method === 'POST') {
+    handlePostRequest(req, res, async (body) => {
+      const { projectPath, scope, event, hookData } = body;
+      if (!scope || !event || !hookData) {
+        return { error: 'scope, event, and hookData are required', status: 400 };
+      }
+      return saveHookToSettings(projectPath, scope, event, hookData);
+    });
+    return true;
+  }
+
+  // API: Delete hook
+  if (pathname === '/api/hooks' && req.method === 'DELETE') {
+    handlePostRequest(req, res, async (body) => {
+      const { projectPath, scope, event, hookIndex } = body;
+      if (!scope || !event || hookIndex === undefined) {
+        return { error: 'scope, event, and hookIndex are required', status: 400 };
+      }
+      return deleteHookFromSettings(projectPath, scope, event, hookIndex);
+    });
+    return true;
+  }
+
+  return false;
+}