@sylphx/flow 1.0.1 → 1.0.3

package/src/domains/codebase/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Codebase domain - Code analysis and search
+ */
+
+export { registerCodebaseSearchTool, registerCodebaseTools } from './tools.js';

package/src/domains/codebase/tools.ts

@@ -0,0 +1,139 @@
+/**
+ * Codebase tools
+ * All tools for working with project source code and files
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { getSearchService } from '../../services/search/unified-search-service.js';
+
+/**
+ * Register codebase search tool
+ */
+export function registerCodebaseSearchTool(server: McpServer): void {
+  server.registerTool(
+    'codebase_search',
+    {
+      description: `Search project source files, documentation, and code. Use this to find implementations, functions, classes, or any code-related content.
+
+**IMPORTANT: Use this tool PROACTIVELY before starting work, not reactively when stuck.**
+
+This tool searches across all codebase files and returns the most relevant matches with content snippets.
+
+When to use this tool (BEFORE starting work):
+- **Before implementation**: Find existing patterns, similar functions, or reusable components
+- **Before refactoring**: Understand current implementation and dependencies
+- **Before adding features**: Check for existing similar functionality or conflicting code
+- **Before debugging**: Search for error messages, function names, or related code
+- **Before writing tests**: Find existing test patterns and test utilities
+
+The search includes:
+- Source code files (.ts, .js, .tsx, .jsx, etc.)
+- Configuration files (.json, .yaml, .toml, etc.)
+- Documentation files (.md, .txt, etc.)
+- Build and deployment files
+
+**Best Practice**: Search the codebase BEFORE writing new code to avoid duplication and follow existing patterns.`,
+      inputSchema: {
+        query: z
+          .string()
+          .describe('Search query - use natural language, function names, or technical terms'),
+        limit: z
+          .number()
+          .default(10)
+          .optional()
+          .describe('Maximum number of results to return (default: 10)'),
+        include_content: z
+          .boolean()
+          .default(true)
+          .optional()
+          .describe('Include file content snippets in results (default: true)'),
+        file_extensions: z
+          .array(z.string())
+          .optional()
+          .describe('Filter by file extensions (e.g., [".ts", ".tsx", ".js"])'),
+        path_filter: z
+          .string()
+          .optional()
+          .describe('Filter by path pattern (e.g., "src/components", "tests", "docs")'),
+        exclude_paths: z
+          .array(z.string())
+          .optional()
+          .describe(
+            'Exclude paths containing these patterns (e.g., ["node_modules", ".git", "dist"])'
+          ),
+      },
+    },
+    async ({
+      query,
+      limit = 10,
+      include_content = true,
+      file_extensions,
+      path_filter,
+      exclude_paths,
+    }) => {
+      try {
+        // Use UnifiedSearchService - same logic as CLI
+        const searchService = getSearchService();
+        await searchService.initialize();
+
+        // Check codebase status
+        const status = await searchService.getStatus();
+
+        // If indexing in progress, show progress
+        if (status.codebase.isIndexing) {
+          const progressBar =
+            '█'.repeat(Math.floor(status.codebase.progress / 5)) +
+            '░'.repeat(20 - Math.floor(status.codebase.progress / 5));
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `⏳ **Codebase Indexing In Progress**\n\nThe codebase is currently being indexed. Please wait...\n\n**Progress:** ${status.codebase.progress}%\n\`${progressBar}\`\n\n**Status:**\n- Files indexed: ${status.codebase.progress > 0 ? Math.floor((status.codebase.fileCount * status.codebase.progress) / 100) : 0}/${status.codebase.fileCount}\n${status.codebase.currentFile ? `- Current file: \`${status.codebase.currentFile}\`` : ''}\n\n**Estimated time:** ${status.codebase.progress > 0 ? 'Less than 1 minute' : 'Starting...'}\n\n💡 **Tip:** Try your search again in a few seconds.`,
+              },
+            ],
+          };
+        }
+
+        if (!status.codebase.indexed) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `📭 **Codebase Not Indexed**\n\nThe codebase has not been indexed yet.\n\n**To fix:**\n- Run: \`sylphx codebase reindex\` from the command line\n- This will create a search index for all source files\n\n**Why this is needed:**\nThe first time you use codebase search, you need to build an index of all files. This only needs to be done once (or when files change significantly).`,
+              },
+            ],
+          };
+        }
+
+        // Perform search using unified service
+        const result = await searchService.searchCodebase(query, {
+          limit,
+          include_content,
+          file_extensions,
+          path_filter,
+          exclude_paths,
+        });
+
+        // Return MCP-formatted results
+        return searchService.formatResultsForMCP(result.results, query, result.totalIndexed);
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `✗ Codebase search error: ${(error as Error).message}`,
+            },
+          ],
+        };
+      }
+    }
+  );
+}
+
+/**
+ * Register all codebase tools
+ */
+export function registerCodebaseTools(server: McpServer): void {
+  registerCodebaseSearchTool(server);
+}

package/src/domains/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Domains Index
+ * Unified exports for all domain modules
+ */
+
+export * from './codebase/index.js';
+export * from './knowledge/index.js';
+export * from './utilities/index.js';

package/src/domains/knowledge/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Knowledge domain - Documentation and guides
+ */
+
+export { getKnowledgeContent } from './resources.js';
+export {
+  registerKnowledgeGetTool,
+  registerKnowledgeSearchTool,
+  registerKnowledgeTools,
+} from './tools.js';

package/src/domains/knowledge/resources.ts

@@ -0,0 +1,537 @@
+/**
+ * Knowledge Resources - 知識庫資源
+ * 動態掃描文件夾並讀取 frontmatter 來提供知識庫內容
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { logger } from '../../utils/logger.js';
+import { getKnowledgeDir } from '../../utils/paths.js';
+
+export interface KnowledgeResource {
+  uri: string;
+  title: string;
+  description: string;
+  content: string;
+  category: 'stacks' | 'guides' | 'universal' | 'data';
+  filePath?: string;
+  lastModified?: string;
+}
+
+export interface KnowledgeFrontmatter {
+  name: string;
+  description: string;
+  category?: string;
+  tags?: string[];
+  author?: string;
+  lastUpdated?: string;
+}
+
+/**
+ * 知識庫配置
+ */
+interface KnowledgeConfig {
+  knowledgeDir: string;
+  supportedExtensions: string[];
+  cacheTimeout: number; // milliseconds
+}
+
+const DEFAULT_CONFIG: KnowledgeConfig = {
+  knowledgeDir: getKnowledgeDir(),
+  supportedExtensions: ['.md'],
+  cacheTimeout: 5 * 60 * 1000, // 5 minutes
+};
+
+/**
+ * 知識庫掃描器
+ */
+class KnowledgeScanner {
+  private cache = new Map<string, { data: KnowledgeResource[]; timestamp: number }>();
+  private config: KnowledgeConfig;
+
+  constructor(config: Partial<KnowledgeConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * 掃描知識庫目錄並獲取所有資源
+   */
+  async scanKnowledgeResources(): Promise<KnowledgeResource[]> {
+    const cacheKey = 'all_resources';
+    const cached = this.cache.get(cacheKey);
+
+    // 檢查緩存是否有效
+    if (cached && Date.now() - cached.timestamp < this.config.cacheTimeout) {
+      logger.debug('Returning cached knowledge resources');
+      return cached.data;
+    }
+
+    try {
+      logger.info('Scanning knowledge directory', { dir: this.config.knowledgeDir });
+
+      const resources: KnowledgeResource[] = [];
+      const categories = await this.getCategories();
+
+      // 並行掃描所有類別
+      const scanPromises = categories.map(async (category) => {
+        const categoryResources = await this.scanCategory(category);
+        return categoryResources;
+      });
+
+      const categoryResults = await Promise.all(scanPromises);
+      categoryResults.forEach((categoryResources) => {
+        resources.push(...categoryResources);
+      });
+
+      // 緩存結果
+      this.cache.set(cacheKey, {
+        data: resources,
+        timestamp: Date.now(),
+      });
+
+      logger.info('Knowledge scan completed', {
+        totalResources: resources.length,
+        categories: categories.length,
+      });
+
+      return resources;
+    } catch (error) {
+      logger.error('Failed to scan knowledge resources', {
+        error: (error as Error).message,
+        dir: this.config.knowledgeDir,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * 獲取所有類別
+   */
+  private async getCategories(): Promise<string[]> {
+    try {
+      const entries = await fs.readdir(this.config.knowledgeDir, { withFileTypes: true });
+      return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((name) => !name.startsWith('.')); // 忽略隱藏文件夾
+    } catch (error) {
+      logger.warn('Failed to read knowledge directory', {
+        error: (error as Error).message,
+        dir: this.config.knowledgeDir,
+      });
+      return [];
+    }
+  }
+
+  /**
+   * 掃描特定類別
+   */
+  private async scanCategory(category: string): Promise<KnowledgeResource[]> {
+    const categoryPath = path.join(this.config.knowledgeDir, category);
+    const resources: KnowledgeResource[] = [];
+
+    try {
+      const files = await fs.readdir(categoryPath);
+      const markdownFiles = files.filter((file) =>
+        this.config.supportedExtensions.some((ext) => file.endsWith(ext))
+      );
+
+      // 並行處理所有文件
+      const filePromises = markdownFiles.map(async (file) => {
+        const filePath = path.join(categoryPath, file);
+        return this.processFile(filePath, category);
+      });
+
+      const fileResults = await Promise.allSettled(filePromises);
+      fileResults.forEach((result, index) => {
+        if (result.status === 'fulfilled' && result.value) {
+          resources.push(result.value);
+        } else if (result.status === 'rejected') {
+          logger.warn('Failed to process knowledge file', {
+            file: markdownFiles[index],
+            error: result.reason,
+          });
+        }
+      });
+
+      logger.debug('Category scan completed', {
+        category,
+        filesFound: markdownFiles.length,
+        resourcesProcessed: resources.length,
+      });
+
+      return resources;
+    } catch (error) {
+      logger.warn('Failed to scan category', {
+        category,
+        error: (error as Error).message,
+      });
+      return [];
+    }
+  }
+
+  /**
+   * 處理單個文件
+   */
+  private async processFile(filePath: string, category: string): Promise<KnowledgeResource | null> {
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      const frontmatter = this.parseFrontmatter(content);
+
+      if (!frontmatter) {
+        logger.warn('No frontmatter found in file', { filePath });
+        return null;
+      }
+
+      // 生成 URI
+      const fileName = path.basename(filePath, path.extname(filePath));
+      const uri = `knowledge://${category}/${fileName}`;
+
+      // 獲取文件統計信息
+      const stats = await fs.stat(filePath);
+
+      const resource: KnowledgeResource = {
+        uri,
+        title: frontmatter.name,
+        description: frontmatter.description,
+        content: this.extractMainContent(content),
+        category: this.mapCategory(category),
+        filePath,
+        lastModified: stats.mtime.toISOString(),
+      };
+
+      logger.debug('Knowledge resource processed', {
+        uri,
+        title: resource.title,
+        category: resource.category,
+      });
+
+      return resource;
+    } catch (error) {
+      logger.error('Failed to process knowledge file', {
+        filePath,
+        error: (error as Error).message,
+      });
+      return null;
+    }
+  }
+
+  /**
+   * 解析 frontmatter
+   */
+  private parseFrontmatter(content: string): KnowledgeFrontmatter | null {
+    const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+    const match = content.match(frontmatterRegex);
+
+    if (!match) {
+      return null;
+    }
+
+    try {
+      // 簡單的 YAML 解析（可以考慮使用 js-yaml 庫）
+      const frontmatterText = match[1];
+      const frontmatter: Partial<KnowledgeFrontmatter> = {};
+
+      // 解析 key: value 格式
+      frontmatterText.split('\n').forEach((line) => {
+        const colonIndex = line.indexOf(':');
+        if (colonIndex > 0) {
+          const key = line.substring(0, colonIndex).trim();
+          let value = line.substring(colonIndex + 1).trim();
+
+          // 移除引號
+          if (value.startsWith('"') && value.endsWith('"')) {
+            value = value.slice(1, -1);
+          } else if (value.startsWith("'") && value.endsWith("'")) {
+            value = value.slice(1, -1);
+          }
+
+          (frontmatter as any)[key] = value;
+        }
+      });
+
+      // 驗證必需字段
+      if (!frontmatter.name || !frontmatter.description) {
+        return null;
+      }
+
+      return frontmatter as KnowledgeFrontmatter;
+    } catch (error) {
+      logger.warn('Failed to parse frontmatter', {
+        error: (error as Error).message,
+      });
+      return null;
+    }
+  }
+
+  /**
+   * 提取主要內容（移除 frontmatter）
+   */
+  private extractMainContent(content: string): string {
+    const frontmatterRegex = /^---\s*\n[\s\S]*?\n---\s*\n/;
+    return content.replace(frontmatterRegex, '').trim();
+  }
+
+  /**
+   * 映射類別
+   */
+  private mapCategory(folderName: string): 'stacks' | 'guides' | 'universal' | 'data' {
+    const categoryMap: Record<string, 'stacks' | 'guides' | 'universal' | 'data'> = {
+      stacks: 'stacks',
+      guides: 'guides',
+      universal: 'universal',
+      data: 'data',
+      database: 'data',
+      architecture: 'guides',
+      patterns: 'guides',
+    };
+
+    return categoryMap[folderName.toLowerCase()] || 'guides';
+  }
+
+  /**
+   * 根據 URI 獲取完整內容
+   */
+  async getKnowledgeContent(uri: string): Promise<string> {
+    try {
+      const resources = await this.scanKnowledgeResources();
+      const resource = resources.find((r) => r.uri === uri);
+
+      if (!resource) {
+        throw new Error(`Knowledge resource not found: ${uri}`);
+      }
+
+      if (!resource.filePath) {
+        throw new Error(`No file path for resource: ${uri}`);
+      }
+
+      // 讀取完整文件內容
+      const fullContent = await fs.readFile(resource.filePath, 'utf-8');
+      const mainContent = this.extractMainContent(fullContent);
+
+      return mainContent;
+    } catch (error) {
+      logger.error('Failed to get knowledge content', {
+        uri,
+        error: (error as Error).message,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * 清除緩存
+   */
+  clearCache(): void {
+    this.cache.clear();
+    logger.info('Knowledge cache cleared');
+  }
+}
+
+// 全局掃描器實例
+const knowledgeScanner = new KnowledgeScanner();
+
+/**
+ * 獲取所有知識庫資源（動態掃描）
+ */
+export async function getAllKnowledgeResources(): Promise<KnowledgeResource[]> {
+  return knowledgeScanner.scanKnowledgeResources();
+}
+
+/**
+ * 根據 URI 獲取知識庫內容
+ */
+export async function getKnowledgeContent(uri: string): Promise<string> {
+  return knowledgeScanner.getKnowledgeContent(uri);
+}
+
+/**
+ * 根據類別獲取知識庫資源
+ */
+export async function getKnowledgeResourcesByCategory(
+  category: 'stacks' | 'guides' | 'universal' | 'data'
+): Promise<KnowledgeResource[]> {
+  const allResources = await getAllKnowledgeResources();
+  return allResources.filter((resource) => resource.category === category);
+}
+
+/**
+ * 搜索知識庫資源
+ */
+export async function searchKnowledgeResources(
+  query: string,
+  options?: {
+    category?: 'stacks' | 'guides' | 'universal' | 'data';
+    limit?: number;
+  }
+): Promise<KnowledgeResource[]> {
+  const allResources = await getAllKnowledgeResources();
+  const queryLower = query.toLowerCase();
+
+  let filtered = allResources.filter(
+    (resource) =>
+      resource.title.toLowerCase().includes(queryLower) ||
+      resource.description.toLowerCase().includes(queryLower) ||
+      resource.content.toLowerCase().includes(queryLower)
+  );
+
+  // 按類別過濾
+  if (options?.category) {
+    filtered = filtered.filter((resource) => resource.category === options.category);
+  }
+
+  // 限制結果數量
+  if (options?.limit) {
+    filtered = filtered.slice(0, options.limit);
+  }
+
+  return filtered;
+}
+
+/**
+ * 清除知識庫緩存
+ */
+export function clearKnowledgeCache(): void {
+  knowledgeScanner.clearCache();
+}
+
+/**
+ * 註冊 MCP 工具
+ */
+export function registerKnowledgeTools(server: McpServer): void {
+  // 獲取所有知識資源
+  server.tool(
+    'get-all-knowledge-resources',
+    'Get all available knowledge resources',
+    {
+      category: z
+        .enum(['stacks', 'guides', 'universal', 'data'])
+        .optional()
+        .describe('Filter by category'),
+    },
+    async ({ category }) => {
+      try {
+        const resources = category
+          ? await getKnowledgeResourcesByCategory(category)
+          : await getAllKnowledgeResources();
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                {
+                  total: resources.length,
+                  resources: resources.map((r) => ({
+                    uri: r.uri,
+                    title: r.title,
+                    description: r.description,
+                    category: r.category,
+                    lastModified: r.lastModified,
+                  })),
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${(error as Error).message}`,
+            },
+          ],
+        };
+      }
+    }
+  );
+
+  // 獲取知識內容
+  server.tool(
+    'get-knowledge-content',
+    'Get full content of a knowledge resource',
+    {
+      uri: z.string().describe('Knowledge resource URI'),
+    },
+    async ({ uri }) => {
+      try {
+        const content = await getKnowledgeContent(uri);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: content,
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${(error as Error).message}`,
+            },
+          ],
+        };
+      }
+    }
+  );
+
+  // 搜索知識庫
+  server.tool(
+    'search-knowledge',
+    'Search knowledge resources',
+    {
+      query: z.string().describe('Search query'),
+      category: z
+        .enum(['stacks', 'guides', 'universal', 'data'])
+        .optional()
+        .describe('Filter by category'),
+      limit: z.number().optional().describe('Maximum results'),
+    },
+    async ({ query, category, limit }) => {
+      try {
+        const results = await searchKnowledgeResources(query, {
+          category,
+          limit,
+        });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                {
+                  query,
+                  total: results.length,
+                  results: results.map((r) => ({
+                    uri: r.uri,
+                    title: r.title,
+                    description: r.description,
+                    category: r.category,
+                  })),
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${(error as Error).message}`,
+            },
+          ],
+        };
+      }
+    }
+  );
+}